@cyanheads/calculator-mcp-server
Evaluate, simplify, and differentiate mathematical expressions via MCP. STDIO or Streamable HTTP.
1 Tool • 1 Resource • 1 Skill
Overview
Calculator powered by math.js. Verify numeric results, simplify algebraic expressions, and compute symbolic derivatives through one tool.
Tools
Resources
Skills
The server serves it over MCP as skill://calculator-guide/SKILL.md; it also ships in skills/ in the npm package and Docker image.
Capability reference
calculate tool
- One
expression per call, up to 4,000 characters by default. operation selects evaluate (default), simplify, or derivative (requires variable, e.g. "x"); scope assigns numeric variables ({ "x": 5 }) and precision sets 1–16 significant digits, both for evaluate only.
- Covers arithmetic, trigonometry, logarithms, statistics, matrices and linear systems (
lusolve), polynomial roots (polynomialRoot), complex numbers, units, combinatorics, dates as quoted YYYY-MM-DD strings (dateDiff, dateAdd, weekday, isoWeek, daysInMonth), and numeric definite integrals (integrate(f, x, a, b)). Accepts **, ×, ÷, −, and ° (°C, °F) as math.js operators in every operation; × and ** take scalar operands.
numericType selects number, BigNumber (64 significant digits, for values that overflow a 64-bit float), or Fraction (exact rationals, including integer combinatorics and rational roots: 5! → 120/1). Fraction mode returns fraction_unsupported when a result has no exact rational value (sqrt(2), 2^(1/2)), the expression calls a function Fraction mode cannot compute (log2(8), stirlingS2(5, 2)), or it uses a value Fraction mode holds only as a rounded float (pi, random()).
- Returns the result string, result type, original expression, and operation;
simplify sets unchanged: true when it cannot reduce the expression (it does no polynomial factoring or rational cancellation). Failures carry a typed reason and a recovery hint.
calculator://help resource
- Markdown reference for functions, operators, constants, units, limits, and expression syntax; no parameters.
- Worked examples cover scope, matrices, polynomial roots, dates, integrals, complex numbers, precision, each
numericType, 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, and nothing reads a clock (
now() and today() are rejected; pass dates as strings)
- Input validation: expression length limits and rejection of multiple statements; matrix row separators and string contents remain valid; nesting past the call stack fails with
expression_too_deep
- Result validation: blocked result types (functions, parsers, result sets), configurable max result size
- Size limits: functions that build a matrix, range, or string from a size, product, broadcast, index, or precision argument are capped per call,
stirlingS2, bellNumbers, and bernoulli bound their arguments, and each evaluation has a total element budget; oversized requests fail fast with result_too_large. integrate() uses at most 500 subintervals per call
- 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:
Or run it locally:
For other clients, add this to the MCP config file:
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.4 or higher. The built server also runs on Node.js v24+.
Docker
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:
License
Apache-2.0 — see LICENSE for details.