Calculator MCP Server

A minimal, fully functional Model Context Protocol (MCP) server written in Python using the official mcp>=2.0 SDK.

This repository serves as a clear reference implementation for understanding:

• How Python type annotations and docstrings generate JSON Schema for AI agents.

• Local IPC pipes (stdio) vs. modern cloud transport (streamable-http).

• Direct JSON-RPC 2.0 handshake and tool invocation.

Tools Implemented

• add(a, b): Adds two numbers.

• subtract(a, b): Subtracts b from a.

• multiply(a, b): Multiplies two numbers.

• divide(a, b): Divides a by b (with divide-by-zero validation).

Related MCP server: Simple Calculator MCP Server

Quickstart

1. Installation

Ensure you have uv installed:

git clone https://github.com/yuntaozhang999/calculator-mcp.git
cd calculator-mcp
uv sync

2. Local Interactive Inspection (stdio)

Run the MCP Inspector to test the tools via a web UI:

uv run mcp dev server.py

3. Headless stdio Mode

Run directly in headless mode for AI agents (AGY, Claude Code):

uv run mcp run server.py

Running as a Cloud Service (streamable-http)

To run as an HTTP microservice on port 8000:

# In server.py:
if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

Start the service:

uv run python server.py

Testing with curl

1. Initialize session and extract the Mcp-Session-Id header:

curl -i -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

2. List available tools:

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <YOUR_SESSION_ID>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

3. Execute tool call:

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <YOUR_SESSION_ID>" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add","arguments":{"a":100,"b":250}}}'

License

MIT