MCP Calculator Server MCP Server

MCP Calculator Server

This repository provides a minimal Model Context Protocol (MCP) server that exposes simple calculator tools (add, subtract, multiply, divide). It's intended as a clean example you can publish to GitHub and use as a starting point for MCP work.

This README covers: setup, running, testing, and publishing the project.

Quick start (Windows PowerShell)

1. Create and activate a virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install the MCP SDK (inside the venv):

pip install "mcp[cli]"

3. Run the server (stdio transport):

python calculator_server.py

4. Run tests (if you use pytest):

python -m pytest

Requirements

• Python 3.11+ (3.10 may work but 3.11+ recommended)
• mcp package (install with pip install "mcp[cli]")

Running the server

Via stdio (standard input/output)

Default transport — recommended for local testing and Claude Desktop integration:

python calculator_server.py

This starts the server using stdio, which communicates via standard input/output streams. The server will wait for connections from MCP clients (e.g., Claude Desktop, MCP Inspector).

Via HTTP (streamable-http transport)

For local testing over HTTP:

python calculator_server.py --transport streamable-http --host 127.0.0.1 --port 8000

This binds the server to http://127.0.0.1:8000 (localhost only). You can then connect MCP clients via HTTP to this address.

For external access (binding to all interfaces):

python calculator_server.py --transport streamable-http --host 0.0.0.0 --port 8080

⚠️ Warning: Binding to 0.0.0.0 or an explicit external IP will disable DNS rebinding protection, allowing external clients to connect. This may expose the server to DNS rebinding attacks. Only use external binding when you understand the security implications and trust the clients connecting to it.

Custom host/port examples:

# Bind to a specific IP address
python calculator_server.py --transport streamable-http --host 192.168.1.100 --port 5000

# Bind to localhost with a different port
python calculator_server.py --transport streamable-http --host 127.0.0.1 --port 9000

Claude Desktop Configuration

To use the calculator server with Claude Desktop, add the following configuration to your claude_desktop_config.json file (typically located at ~/.claude/claude_desktop_config.json on macOS/Linux or %APPDATA%\Claude\claude_desktop_config.json on Windows).

Via stdio (recommended for Claude Desktop)

{
  "mcpServers": {
    "calculator": {
      "command": "uv",
      "args": [
        "--directory",
        "F:\\mcp2\\VSMCP\\VSMCP",
        "run",
        "python",
        "calculator_server.py"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": ".venv"
      }
    }
  }
}

Replace F:\\mcp2\\VSMCP\\VSMCP with the full path to your project directory.

After updating the config, restart Claude Desktop. The calculator tools will be available in your conversations.

Via HTTP streamable (localhost)

If you prefer to run the server over HTTP on localhost:

{
  "mcpServers": {
    "calculator": {
      "command": "uv",
      "args": [
        "--directory",
        "F:\\mcp2\\VSMCP\\VSMCP",
        "run",
        "python",
        "calculator_server.py",
        "--transport",
        "streamable-http",
        "--host",
        "127.0.0.1",
        "--port",
        "8000"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": ".venv"
      }
    }
  }
}

Replace F:\\mcp2\\VSMCP\\VSMCP with the full path to your project directory.

After updating the config, restart Claude Desktop.

Via HTTP streamable (external access)

If you want external clients to access the server over HTTP:

{
  "mcpServers": {
    "calculator": {
      "command": "uv",
      "args": [
        "--directory",
        "F:\\mcp2\\VSMCP\\VSMCP",
        "run",
        "python",
        "calculator_server.py",
        "--transport",
        "streamable-http",
        "--host",
        "0.0.0.0",
        "--port",
        "8080"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": ".venv"
      }
    }
  }
}

⚠️ Warning: Binding to 0.0.0.0 disables DNS rebinding protection. Only do this if you understand the security implications.

Tests

• Run the included tests with:

python -m pytest

or, if you prefer the single-file runner:

python test_mcp.py

Files removed from repo

I removed the following build / artifact files from the repository because they are not needed in source control:

• __pycache__/ (Python bytecode caches)
• mcp_calculator_server.egg-info/ (packaging metadata)
• nodejs.zip (archival artifact)

If you want any of these preserved, let me know and I can restore them.

Git / Publishing suggestions

• Add these entries to .gitignore (this repo already contains a .gitignore):

.v