Calculator MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Calculator MCP Servercalculate 45 times 12 plus 30"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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): Subtractsbfroma.multiply(a, b): Multiplies two numbers.divide(a, b): Dividesabyb(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 sync2. Local Interactive Inspection (stdio)
Run the MCP Inspector to test the tools via a web UI:
uv run mcp dev server.py3. Headless stdio Mode
Run directly in headless mode for AI agents (AGY, Claude Code):
uv run mcp run server.pyRunning 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.pyTesting with curl
Initialize session and extract the
Mcp-Session-Idheader:
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"}}}'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"}'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 toolsaddB
Add two numbers together.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | ||
| b | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Add two numbers together,' but does not disclose behavioral traits such as result type, precision, overflow handling, or error behavior. For a simple arithmetic tool, this may be passable, but it lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, coherent sentence with no extraneous words. It efficiently conveys the tool's purpose. Front-loading is not an issue due to its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 numbers, arithmetic operation), the description is adequate but incomplete. It does not mention the return value (output schema exists but is not described), nor does it address edge cases, making it insufficient for complex usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning parameters have no descriptions. The description adds no semantic context beyond the schema (that a and b are numbers). It does not explain what the numbers represent, range constraints, or units, leaving the agent with minimal guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add) and the object (two numbers), and it distinguishes from sibling arithmetic tools like subtract, multiply, etc. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when addition is needed, but provides no explicit guidance on when to use this tool versus alternatives, nor any context about prerequisites or restrictions. The sibling tools differentiate by operation, but the description does not elaborate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
divideC
Divide a by b.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | ||
| b | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavioral traits. It only states the division operation and says nothing about edge cases like division by zero, error handling, or return type behavior. For a pure computation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It conveys the essential operation and operand order compactly, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simple nature of the tool, the description omits key behavioral context such as division-by-zero behavior. An output schema exists but likely only describes the return type, not error cases. The description is too sparse to be considered complete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds the crucial semantic that 'a' is the dividend and 'b' is the divisor. However, it does not provide additional constraints or expectations (e.g., non-zero denominator), leaving the agent to assume the schema's minimal information is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Divide a by b' clearly states the operation and the roles of the two operands, distinguishing it from add, subtract, and multiply. It is not a mere tautology of the tool name because it specifies the argument order, making the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus the sibling arithmetic tools or any exclusions. While the operation is self-evident, the description does not explicitly state conditions or alternatives, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
multiplyA
Multiply a and b.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | ||
| b | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
For a pure arithmetic operation, 'Multiply a and b' transparently conveys behavior: no side effects, no mutation, no hidden state. With no annotations provided, the description is adequate, though it does not discuss edge cases like overflow or type coercion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero filler, and the core operation is front-loaded. This is appropriately sized for a two-parameter pure function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, the input schema fully specifies both required numeric parameters, and an output schema is present. Nothing essential is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameter roles. It identifies a and b as the multiplicands, but adds no further semantic detail beyond what the schema's number type and requiredness already provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact operation ('Multiply') on the named operands a and b, which fully specifies the tool's function. It is clearly distinct from its arithmetic siblings add, subtract, and divide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage must be inferred from the operation itself: an agent needing a product would select this tool. However, no explicit guidance or alternatives are named, and there are no statements about when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
subtractA
Subtract b from a.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | ||
| b | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of explaining behavior. It clearly specifies the order of operands (b from a) but does not disclose additional traits such as return type, edge cases, or side effects. For a simple arithmetic function, this is minimal but adequate; however, it lacks richness beyond the core operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler words. It communicates the essential operation clearly and efficiently, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool, the explicit input schema, and the presence of an output schema (as indicated by context), the description provides sufficient context. It does not need to explain return values or complex behaviors, making it complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has no descriptions for a and b, the description adds critical semantic meaning by clarifying the subtractive relationship: a is the minuend and b is the subtrahend. This compensates for the 0% schema description coverage and helps the agent understand how to correctly pass arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action as 'Subtract b from a', using a specific verb and resource. This unambiguously identifies the operation and distinguishes it from sibling tools like add, multiply, and divide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for subtraction but does not explicitly state when to choose this tool over alternatives. There is no mention of exclusions or competing tools, leaving the usage context to be inferred from the operation name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.1.0- First observed
add - First observed
divide - First observed
multiply - First observed
subtract
TDQS
Scored across 4 tools
Each tool performs a single, distinct arithmetic operation with no overlap. An agent can easily select the correct tool based on the desired operation.
All tool names follow a consistent lowercase verb pattern: add, subtract, multiply, divide. The naming is predictable and uniform.
Four tools is an ideal scope for a basic calculator server. Each tool covers a fundamental operation without unnecessary bloat.
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
Related MCP Connectors
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
Math.js MCP — wraps the mathjs.org API (free, no auth)
17 Base data tools for agents over Streamable HTTP MCP. Pay per call in USDC via x402; no API key.
Tested financial & practical calculators as free, no-auth MCP tools for AI agents.
Related MCP Servers
- FlicenseDqualityDmaintenanceProvides basic mathematical operations (addition, subtraction, multiplication, division) through a calculate tool. Supports both stdio and HTTP/SSE transport modes.16 npm-
- AlicenseNot gradedqualityDmaintenanceEnables basic arithmetic operations (add, subtract, multiply, divide, modulo) via natural language, with a FastMCP-based server and client for exploring MCP tool calling.MIT
- AlicenseAqualityBmaintenanceProvides basic arithmetic operations (add, subtract, multiply, divide) through MCP, enabling AI clients to perform calculations via natural language.420 npmMIT
- FlicenseNot gradedqualityCmaintenanceEnables arithmetic operations such as addition and calculating averages, exposing tools via MCP with stdio and Streamable HTTP transports.-