Calculator Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.6.0Updated Nov 12, 2026

Evaluate, simplify, and differentiate mathematical expressions.

The publisher's own server: Calculator Tools MCP

VerifiedStreamable HTTPWeb executableDeveloper ToolsData & Analytics

Overview

AI-generated overview

A math.js-backed MCP server whose single calculate tool lets an assistant evaluate, simplify and differentiate expressions, including matrices, units and dates.

What you can do
  • Evaluate numeric expressions with variable scope and 1-16 digit precision
  • Simplify algebraic expressions and compute symbolic derivatives with a named variable
  • Work with matrices, linear systems, polynomial roots, complex numbers, statistics and combinatorics
  • Convert units and do date arithmetic on quoted YYYY-MM-DD dates, plus numeric definite integrals
  • Read a help resource listing operators, functions, limits and worked examples
When to use it
Useful when an assistant needs to check arithmetic or numeric claims rather than guess, or when a task involves symbolic simplification, derivatives, unit conversion, matrix solving or date differences. It is a lightweight, read-only addition for any workflow where verified math matters.
Requirements
Either the public hosted endpoint or a local process via npx (Node.js), Bun for source builds, or the Docker image. No account or API key is needed; optional environment variables tune expression length, evaluation timeout, result size, transport, host, port, endpoint path, auth mode and log level.
Before you install
All operations are read-only and stateless, and no credentials are requested. Results are only as reliable as the expression given: simplify may return the input unchanged, Fraction mode can fail on irrational results, and floating-point comparisons need tolerances. The hosted endpoint sends your expressions to a third-party server, so avoid pasting confidential values.

Installation

In SourceWeft

  1. Open Calculator Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fcalculator-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

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

README

@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

ToolDescription
calculateEvaluate math expressions, simplify algebraic expressions, or compute symbolic derivatives.

Resources

ResourceDescription
calculator://helpAvailable functions, operators, constants, and syntax reference.

Skills

SkillDescription
calculator-guideWhich numericType answers which question, what a result does not prove (integer-looking floats, tolerance-based ==, lusolve on a singular matrix, a simplify that stops short of 0), and workflows for derivative checks, business-day deadlines, statistics by dimension, unit chains, and integral tails

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:

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

Or run it locally:

sh
claude mcp add calculator-mcp-server -- npx -y @cyanheads/calculator-mcp-server

For other clients, add this to the MCP config file:

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

For Docker or a source build, see Running the server.

Configuration

VariableDescriptionDefault
CALC_MAX_EXPRESSION_LENGTHMaximum allowed expression string length (10–10,000).4000
CALC_EVALUATION_TIMEOUT_MSMaximum evaluation time in milliseconds (100–30,000).5000
CALC_MAX_RESULT_LENGTHMaximum result string length in characters (1,000–1,000,000).100000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_HOSTHostname for the HTTP server.127.0.0.1
MCP_HTTP_PORTPort for HTTP server.3010
MCP_HTTP_ENDPOINT_PATHPath for the HTTP MCP endpoint./mcp
MCP_HTTP_MAX_BODY_BYTESMaximum inbound HTTP request size; 0 disables the limit.1048576
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_SESSION_MODEauto, 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_LEVELLog level (RFC 5424).info

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+.

  • Clone and install:

    sh
    git clone https://github.com/cyanheads/calculator-mcp-server.gitcd calculator-mcp-server && bun installcp .env.example .env
  • Build and run the production version:

    sh
    bun run buildbun run start:http   # or start:stdio
  • Run checks and tests:

    sh
    bun run devcheck     # Lints, formats, type-checksbun run test         # Runs test suite

Docker

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/calculator-mcp-server:latest

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

DirectoryPurpose
src/mcp-server/tools/Tool definitions (*.tool.ts).
src/mcp-server/resources/Resource definitions (*.resource.ts).
src/services/Domain service integrations (MathService).
skills/Published skills, served over MCP and shipped in the package.
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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

Source: README.md at commit 7994e70

Tools

1

calculate

Calculate

Evaluate math expressions, simplify algebraic expressions, or compute symbolic derivatives. One expression per call. Supports arithmetic, trigonometry, statistics, matrices, linear systems, polynomial roots, complex numbers, units, combinatorics, calendar dates (quoted YYYY-MM-DD strings), and numeric definite integrals.

ParametersscopevariableoperationprecisionexpressionrequirednumericType

Version history

7
  1. v0.6.0LatestNov 12, 2026
  2. v0.5.3Oct 29, 2026
  3. v0.5.2Oct 25, 2026
  4. v0.5.1Oct 8, 2026
  5. v0.5.0Sep 25, 2026
  6. v0.4.3Sep 19, 2026
  7. v0.4.2Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Calculator integrations