Package Exports

@cyanheads/calculator-mcp-server
@cyanheads/calculator-mcp-server/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@cyanheads/calculator-mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@cyanheads/calculator-mcp-server

A calculator MCP server that lets any LLM verify mathematical computations. Evaluate, simplify, and differentiate expressions via a single tool. Powered by math.js v15.

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), variable name regex enforcement
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:

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

Self-Hosted / Local

Add to your MCP client config (e.g., claude_desktop_config.json):

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

Prerequisites

Bun v1.2.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_PORT`	Port for HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`

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

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.