@cyanheads/calculator-mcp-server

Evaluate, simplify, and differentiate mathematical expressions via MCP. STDIO or Streamable HTTP.

1 Tool • 1 Resource

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

Tools

One tool for all mathematical operations:

Tool Name	Description
`calculate`	Evaluate math expressions, simplify algebraic expressions, or compute symbolic derivatives.

`calculate`

A single tool covering 100% of the server's purpose. The operation parameter defaults to evaluate, so the common case is just { expression: "..." }.

Evaluate — arithmetic, trigonometry, logarithms, statistics, matrices, complex numbers, unit conversion, combinatorics
Simplify — reduce algebraic expressions symbolically (e.g., 2x + 3x -> 5 * x). Supports algebraic and trigonometric identities
Derivative — compute symbolic derivatives (e.g., 3x^2 + 2x + 1 -> 6 * x + 2)
Variable scope via scope parameter: { "x": 5, "y": 3 }
Configurable precision for numeric results
Blank optional variable and precision values from form-based MCP clients are treated as omitted

Resources

URI Pattern	Description
`calculator://help`	Available functions, operators, constants, and syntax reference.

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling across all tools
Structured logging with optional OpenTelemetry tracing
Runs locally (stdio/HTTP) or in Docker

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, expression separator rejection (semicolons and newlines), numeric-only scope values
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.)

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:

config.json

{
  "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:

config.json

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

Or with npx (no Bun required):

config.json

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

Or with Docker:

config.json

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

Prerequisites

Bun v1.3.0 or higher

Installation

Clone the repository:

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

Navigate into the directory:

cd calculator-mcp-server

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.	`localhost`
`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_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

Terminal

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.

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.

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 and pull requests are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.