calculator-mcp-server

---

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

Public Hosted Instance

A public instance is available at https://calculator.caseyjhand.com/mcp — no installation required. It serves Streamable HTTP; each client takes its own config shape.

For Claude Code:

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

For Cline (cline_mcp_settings.json):

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "streamableHttp",
      "url": "https://calculator.caseyjhand.com/mcp"
    }
  }
}

For Cursor (mcp.json):

{
  "mcpServers": {
    "calculator-mcp-server": {
      "url": "https://calculator.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop adds remote servers under Settings → Connectors.

Self-Hosted / Local

Add one of the following to your MCP client configuration file:

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/calculator-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/calculator-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/calculator-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the built server:

MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/calculator-mcp-server.git

2. Navigate into the directory:

cd calculator-mcp-server

3. Install dependencies:

bun install

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

• 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 build -t calculator-mcp-server .
docker run -p 3010:3010 calculator-mcp-server

The image defaults to Streamable HTTP on port 3010, stateless sessions, and logs at /var/log/calculator-mcp-server. OpenTelemetry dependencies are installed by default; build with --build-arg OTEL_ENABLED=false to omit 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.