calculator-mcp-server

<div align="center"> <h1>@cyanheads/calculator-mcp-server</h1> <p><b>Evaluate, simplify, and differentiate mathematical expressions via MCP. STDIO or Streamable HTTP.</b> <div>1 Tool • 1 Resource</div> </p> </div> <div align="center">

</div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://calculator.caseyjhand.com/mcp

</div>

---

Overview

Calculator powered by math.js. Verify numeric results, simplify algebraic expressions, and compute symbolic derivatives through one tool.

Tools

| Tool | Description | |:----------|:------------| | calculate | Evaluate math expressions, simplify algebraic expressions, or compute symbolic derivatives. |

Resources

| Resource | Description | |:------------|:------------| | calculator://help | Available functions, operators, constants, and syntax reference. |

Capability reference

calculate _tool

• One expression per call. operation selects evaluate (default), simplify, or derivative; derivatives require variable (e.g. "x").
• Evaluate arithmetic, trigonometry, logarithms, statistics, matrices, complex numbers, units, and combinatorics; assign numeric variables through scope, e.g. { "x": 5 }.
• numericType selects number, BigNumber (64 significant digits, for values that overflow a 64-bit float), or Fraction (exact rationals). Fraction mode returns fraction_unsupported, with guidance to change numeric type, when a result has no exact rational value (sqrt(2)), the expression calls a function Fraction mode cannot compute (sqrt(4), 5!), or it uses a value Fraction mode holds only as a rounded float (pi, 2^(1/2)).
• precision sets 1–16 significant digits for numeric results. Blank optional variable and precision values are treated as omitted; scope and precision do not affect symbolic operations.
• Simplification includes algebraic and trigonometric identities (2x + 3x → 5 * x); unchanged: true identifies expressions the simplifier cannot reduce, including polynomial factoring and rational cancellation cases.
• Returns the result string, result type, original expression, and operation. Validation failures include typed reasons and recovery hints.

---

calculator://help _resource

• Markdown reference for functions, operators, constants, units, and expression syntax; no parameters.
• Examples cover scope, matrices, complex numbers, precision, and all three operations.
• Cacheable for 24 hours with public scope (cacheHint) — static content that never changes at runtime.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Calculator-specific:

• Hardened math.js v15 instance — dangerous functions disabled, evaluation run under a vm timeout
• No auth required — all operations are read-only and stateless
• Input validation: expression length limits and rejection of multiple statements; matrix row separators and string contents remain valid
• Result validation: blocked result types (functions, parsers, result sets), configurable max result size
• Size limits: functions that build a matrix or string from a size, product, broadcast, index, or precision argument are capped per call, and each evaluation has a total element budget; oversized requests fail fast with result_too_large
• Scope sanitization: numeric-only values, prototype pollution prevention (blocked __proto__, constructor, etc.)

Agent-friendly output:

• Effective-call echo — every response echoes the expression and operation, plus which scope variables and what precision were applied, so agents can verify what was actually computed
• Discriminated output contracts — unchanged: true on simplify flags a no-op result instead of silently returning the same expression
• Typed error reasons — validation and evaluation failures carry a typed reason (e.g. fraction_unsupported, evaluation_timeout, disallowed_result_type) plus an actionable recovery hint, rather than a raw exception

Getting started

Connect to the hosted instance, no install:

claude mcp add --transport http calculator-mcp-server https://calculator.caseyjhand.com/mcp

Or run it locally:

claude mcp add calculator-mcp-server -- npx -y @cyanheads/calculator-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "calculator-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/calculator-mcp-server"]
    }
  }
}

For Docker or a source build, see Running the server.

Configuration

| Variable | Description | Default | |:---------|:------------|:--------| | CALC_MAX_EXPRESSION_LENGTH | Maximum allowed expression string length (10–10,000). | 1000 | | CALC_EVALUATION_TIMEOUT_MS | Maximum evaluation time in milliseconds (100–30,000). | 5000 | | CALC_MAX_RESULT_LENGTH | Maximum result string length in characters (1,000–1,000,000). | 100000 | | MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio | | MCP_HTTP_HOST | Hostname for the HTTP server. | 127.0.0.1 | | MCP_HTTP_PORT | Port for HTTP server. | 3010 | | MCP_HTTP_ENDPOINT_PATH | Path for the HTTP MCP endpoint. | /mcp | | MCP_HTTP_MAX_BODY_BYTES | Maximum inbound HTTP request size; 0 disables the limit. | 1048576 | | MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none | | MCP_SESSION_MODE | auto, stateful, or stateless. The server declares stateless in code, so every launch path resolves the same way; setting this overrides that declaration. | stateless | | MCP_LOG_LEVEL | Log level (RFC 5424). | info |

See .env.example for optional session, resumability, logging, and telemetry settings.

Running the server

Local development

Requires Bun v1.4.0 or higher. The built server also runs on Node.js v24+.

• Clone and install:

  git clone https://github.com/cyanheads/calculator-mcp-server.git
  cd calculator-mcp-server && bun install
  cp .env.example .env
  

• Build and run the production version:

  bun run build
  bun run start:http   # or start:stdio
  

• Run checks and tests:

  bun run devcheck     # Lints, formats, type-checks
  bun run test         # Runs test suite
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/calculator-mcp-server:latest

The image defaults to Streamable HTTP on port 3010, stateless sessions, and logs at /var/log/calculator-mcp-server. For stdio, use docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/calculator-mcp-server:latest. To build locally, run docker build -t calculator-mcp-server .; OpenTelemetry dependencies are installed by default, and --build-arg OTEL_ENABLED=false omits them.

Project structure

| Directory | Purpose | |:----------|:--------| | src/mcp-server/tools/ | Tool definitions (*.tool.ts). | | src/mcp-server/resources/ | Resource definitions (*.resource.ts). | | src/services/ | Domain service integrations (MathService). | | src/config/ | Environment variable parsing and validation with Zod. | | docs/ | Generated directory tree. | | tests/ | Calculation, configuration, and response-contract tests. |

Development guide

See AGENTS.md or CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging
• Register new tools and resources in src/index.ts

Contributing

Issues are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.