Calc MCP

npm version License: MIT 📖 Documentation — Full tool reference, examples, and install guides.

21 tools for things AI is not good at — deterministic math, cryptographic randomness, accurate date arithmetic, encoding, hashing, and more.

LLMs hallucinate calculations, can't generate true random numbers, and struggle with timezones. This MCP server fixes that.

Quick Start

# Claude Code
claude mcp add -s user calc-mcp -- npx -y @coo-quack/calc-mcp@2.1.0

# Or just run it
npx -y @coo-quack/calc-mcp@2.1.0

Works with Claude Desktop, VS Code Copilot, Cursor, Windsurf, and any MCP client — setup guides below.

Why?

AI alone	With calc-mcp
"10 + 34 × 341 ÷ 23 = 507.8" ❌	`514.087` ✅ (math)
"Here's a UUID: 550e8400-..." 🤷 fake	Cryptographically random UUID v4/v7 ✅ (random)
"100 days from now is..." 🤔 guess	`2026-05-22` ✅ (date)
"SHA-256 of password123 is..." 💀 hallucinated	`{"hash": "ef92b778bafe..."}` ✅ (hash)

Deterministic — Same input, same correct output, every time
Secure — Sandboxed math, ReDoS protection, weak hash warnings
Private — All computation runs locally, no data sent to external services
No server config — Install once via npx; MCP client setup required
No API key — No account or API key required for calc-mcp itself; requires Node.js

Examples

Ask in natural language — your AI assistant selects the appropriate tool.

Math & Numbers

You ask	You get	Tool
What's 10 + 34 × 341 ÷ 23?	`514.087`	math
Convert 255 to binary	`11111111`	base
Is 4539578763621486 a valid card number?	`true`	luhn

Text & Encoding

You ask	You get	Tool
How many characters in "Hello, World! 🌍"?	`15 chars, 18 bytes`	count
Base64 encode "Hello World"	`SGVsbG8gV29ybGQ=`	base64
Base64 decode "eyJhbGciOiJIUzI1NiJ9"	`{"alg":"HS256"}`	base64
URL-encode "hello world"	`hello%20world`	encode
URL-decode "hello%20world"	`hello world`	encode
HTML-decode `<script>`	`<script>`	encode
SHA-256 hash of "password123"	`{"hash": "ef92b778bafe..."}`	hash
HMAC-SHA256 of "message" with key "secret"	`{"hash": "8b5f48702995..."}`	hash

Date & Time

You ask	You get	Tool
What time is it in New York?	`2026-02-10T19:00:00-05:00`	datetime
What's 100 days after 2026-02-11?	`2026-05-22`	date
When does "30 9 * * 1-5" run?	`Mon–Fri at 9:30`	cron_parse

Generation

You ask	You get	Tool
Generate a UUID v7	`019c4b54-aad2-7e52-...`	random
Generate a readable 20-char password	`hT9jZDojX6sHRJt8vaKS`	random
Shuffle ["Alice", "Bob", "Charlie"]	`["Charlie", "Alice", "Bob"]`	random

Conversion

You ask	You get	Tool
100 miles in kilometers?	`160.93 km`	convert
72°F in Celsius?	`22.22°C`	convert
Convert #FF5733 to RGB	`rgb(255, 87, 51)`	color
Convert rgba(255, 0, 0, 0.5) to 8-digit HEX	`#ff000080`	color

Analysis & Parsing

You ask	You get	Tool
Extract numbers from "abc123def456"	`123, 456`	regex
Does 1.5.3 satisfy ^1.0.0?	`true`	semver
Does 1.8.0 satisfy ">=1.5.0 <2.0.0"?	`true`	semver
IP range of 192.168.1.0/24?	`192.168.1.1 – .254 (254 hosts)`	ip
Edit distance: "kitten" → "sitting"	`3`	diff
Unicode info for "€"	`U+20AC, Currency Symbols`	char_info
Is `{"name":"test"}` valid JSON?	`valid, object`	format_validate

Decode & Parse

You ask	You get	Tool
Decode this JWT: eyJhbGci...	`{ alg: "HS256", name: "John Doe" }`	jwt_decode
Parse https://example.com/search?q=hello	`host: example.com, q: "hello"`	url_parse

All 21 Tools

Tool	Description
`math`	Evaluate expressions, statistics
`count`	Characters (grapheme-aware), words, lines, bytes
`datetime`	Current time, timezone conversion, UNIX timestamps
`random`	UUID v4/v7, ULID, passwords (readable, custom charset), random number, shuffle
`hash`	MD5, SHA-1, SHA-256, SHA-512, CRC32, HMAC
`base64`	Encode / decode
`encode`	URL, HTML entity, Unicode escape
`date`	Diff, add/subtract, weekday, wareki
`regex`	Test, match, matchAll, replace
`base`	Number base conversion (2–36)
`diff`	Line diff, Levenshtein distance
`format_validate`	Validate JSON, CSV, XML, YAML
`cron_parse`	Human-readable cron + next runs (weekday/month names supported)
`luhn`	Validate / generate check digits
`ip`	IPv4/IPv6 info, CIDR contains check, range calculation
`color`	HEX ↔ RGB ↔ HSL (alpha channel supported)
`convert`	8 categories, 146 unit names: length, weight, temperature, area (tsubo, tatami), volume, speed, data, time
`char_info`	Unicode code point, block, category
`jwt_decode`	Decode header + payload (no verification)
`url_parse`	Protocol, host, path, params, hash
`semver`	Compare, validate, parse, range satisfaction

Install

Claude Code

claude mcp add -s user calc-mcp -- npx -y @coo-quack/calc-mcp@2.1.0

Claude Code plugin

Also available as a plugin from the coo-quack marketplace:

/plugin marketplace add coo-quack/claude-code-marketplace
/plugin install calc-mcp@coo-quack

See the installation guide for details.

Claude Desktop / Cursor / Windsurf

Add to your config file:

App	Config path
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`

{
  "mcpServers": {
    "calc-mcp": {
      "command": "npx",
      "args": ["-y", "@coo-quack/calc-mcp@2.1.0"]
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "calc-mcp": {
      "command": "npx",
      "args": ["-y", "@coo-quack/calc-mcp@2.1.0"]
    }
  }
}

Docker Image

Calc MCP is available as a Docker image from GitHub Container Registry:

docker run --rm -i ghcr.io/coo-quack/calc-mcp:latest

Or use in MCP client config:

{
  "mcpServers": {
    "calc-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/coo-quack/calc-mcp:latest"]
    }
  }
}

Available tags:

ghcr.io/coo-quack/calc-mcp:latest — Latest release
ghcr.io/coo-quack/calc-mcp:X.Y.Z — Specific version (replace X.Y.Z with the desired version)

Other MCP Clients

Calc MCP works with any MCP-compatible client. Run the server via stdio:

npx -y @coo-quack/calc-mcp@2.1.0

Point your client's MCP config to the command above. The server communicates over stdio using the standard Model Context Protocol.

Development

bun install
bun run dev       # Start dev server
bun test          # Run tests
bun run lint      # Biome
bun run format    # Biome

Security

calc-mcp processes all data locally and does not:

❌ Send data to external servers
❌ Log data to files or remote services
❌ Store processed data persistently

For detailed security information, see SECURITY.md.

Safe Usage with LLMs

calc-mcp itself is local-only. However, when used via an LLM, your inputs are sent to the LLM provider (Anthropic, OpenAI, etc.).

✅ DO: Use test/sample data when possible
✅ DO: Use local-only LLMs for sensitive operations
❌ DON'T: Pass production secrets to MCP tools (they will be sent to your LLM provider)

Example:

# ❌ Unsafe: Any secret passed to MCP tool is sent to your LLM provider
# Tool: hash
# Input: { "input": "sk-1234567890abcdef", "algorithm": "sha256" }

# ✅ Safe: Use test data only (for learning/development)
# Tool: hash
# Input: { "input": "test-value-123", "algorithm": "sha256" }

# ✅ For production secrets: Use local-only LLMs or process outside MCP

Note: Error messages are automatically sanitized to prevent accidental data leakage.

For security issues, please see our Security Policy.

License

MIT