cyanheads/calculator-mcp-server

imageVersion imageLicense imageDocker imageMCP SDK imagenpm imageTypeScript imageBun

imageInstall in Claude Desktop imageInstall in Cursor imageInstall in VS Code

imageFramework

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

Overview

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

Tools

Resources

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

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

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.