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. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

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, or Fraction. Fractions require exact rational results; irrational or transcendental results return fraction_unsupported with guidance to change numeric type.
• 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 sandboxed via vm.runInNewContext() with 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
• 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. Point any MCP client at it via Streamable HTTP:

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

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.