Summary
A hardened math.js wrapper that gives Claude a single `calculate` tool for evaluation, symbolic simplification, and derivatives. Handles arithmetic, trig, matrices, unit conversion, and more with configurable precision and variable scoping. Built with sandbox isolation (disabled dangerous functions, vm context with timeout, input validation blocking semicolons and prototype pollution). Ships as both stdio and streamable HTTP with a public hosted instance at calculator.caseyjhand.com, so you can point Claude at it without installing anything. Reach for this when you need Claude to crunch numbers, simplify algebraic expressions, or compute symbolic derivatives without writing your own math service.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
1 tools
calculateEvaluate math expressions, simplify algebraic expressions, or compute symbolic derivatives. Supports arithmetic, trigonometry, statistics, matrices, complex numbers, units, and combinatorics.5 params
Evaluate math expressions, simplify algebraic expressions, or compute symbolic derivatives. Supports arithmetic, trigonometry, statistics, matrices, complex numbers, units, and combinatorics.
Parameters* required
scopeobjectVariable assignments for the expression. Example: { "x": 5, "y": 3 } makes "x + y" evaluate to 8.
variablevalueVariable to differentiate with respect to. Required when operation is "derivative". Blank values from form-based clients are treated as omitted. Example: "x".
operationstringOperation to perform. "evaluate" computes a numeric result (default). "simplify" reduces an algebraic expression symbolically (e.g., "2x + 3x" -> "5 * x"). Supports algebraic and trigonometric identities. "derivative" computes the symbolic derivative (requires the variable parameter).one of
evaluate · simplify · derivativedefault: evaluateprecisionvalueSignificant digits (1–16) for numeric results. Omit for full precision. Blank values from form-based clients are treated as omitted. Ignored for symbolic operations (simplify, derivative).
expressionstringMathematical expression to evaluate. Supports standard notation: arithmetic (+, -, *, /, ^, %), functions (sin, cos, sqrt, log, abs, round, etc.), constants (pi, e, phi, i), matrices ([1, 2; 3, 4]), units (5 kg to lbs), and variables (when scope is provided).
@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
scopeparameter:{ "x": 5, "y": 3 } - Configurable precision for numeric results
- Blank optional
variableandprecisionvalues 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-mcp-server": {
"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-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@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_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/catchin tool logic - Use
ctx.logfor 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.
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
CALC_MAX_EXPRESSION_LENGTHdefault: 1000Maximum allowed expression string length.
CALC_EVALUATION_TIMEOUT_MSdefault: 5000Maximum evaluation time in milliseconds.
CALC_MAX_RESULT_LENGTHdefault: 100000Maximum result string length in characters.
MCP_LOG_LEVELdefault: infoSets the minimum log level for output (e.g., 'debug', 'info', 'warn').
MCP_HTTP_HOSTdefault: 127.0.0.1The hostname for the HTTP server.
MCP_HTTP_PORTdefault: 3010The port to run the HTTP server on.
MCP_HTTP_ENDPOINT_PATHdefault: /mcpThe endpoint path for the MCP server.
MCP_AUTH_MODEdefault: noneAuthentication mode to use: 'none', 'jwt', or 'oauth'.
Registryactive
Package@cyanheads/calculator-mcp-server
TransportSTDIO, HTTP
UpdatedJun 4, 2026