Skip to main content
Glama
Calculator MCP Server

Calculator MCP Server

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: 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"}}}'
  1. 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"}'
  1. 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

Available Tools

4 tools
addB

Add two numbers together.

Inputs: a (required), b (required). Returns: result

divideC

Divide a by b.

Inputs: a (required), b (required). Returns: result

multiplyA

Multiply a and b.

Inputs: a (required), b (required). Returns: result

subtractA

Subtract b from a.

Inputs: a (required), b (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool performs a single, distinct arithmetic operation with no overlap. An agent can easily select the correct tool based on the desired operation.

    Naming Consistency5/5

    All tool names follow a consistent lowercase verb pattern: add, subtract, multiply, divide. The naming is predictable and uniform.

    Tool Count5/5

    Four tools is an ideal scope for a basic calculator server. Each tool covers a fundamental operation without unnecessary bloat.

    Completeness4/5

    The four basic arithmetic operations are fully covered, which satisfies the core purpose. Minor gaps like modulo or exponentiation exist but are not essential for a simple calculator.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      D
      quality
      D
      maintenance
      Provides basic mathematical operations (addition, subtraction, multiplication, division) through a calculate tool. Supports both stdio and HTTP/SSE transport modes.
      1
      ISC
    • F
      license
      A
      quality
      D
      maintenance
      Provides basic arithmetic operations (add, subtract, multiply, divide) through MCP, enabling AI clients to perform calculations via natural language.
      4
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables arithmetic operations such as addition and calculating averages, exposing tools via MCP with stdio and Streamable HTTP transports.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to perform arithmetic operations such as addition, subtraction, multiplication, and division through standardized MCP tools.
      1
      -