Calc MCP

📖 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 --prefix /tmp -y @coo-quack/calc-mcp@latest

# Or just run it
npx --prefix /tmp -y @coo-quack/calc-mcp@latest

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	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 &lt;script&gt;	<script>	encode
SHA-256 hash of "password123"	ef92b778bafe...	hash
HMAC-SHA256 of "message" with key "secret"	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	json_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
json_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, 72 units: 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 --prefix /tmp -y @coo-quack/calc-mcp@latest

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": ["--prefix", "/tmp", "-y", "@coo-quack/calc-mcp@latest"]
    }
  }
}

VS Code (GitHub Copilot)

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

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

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 --prefix /tmp -y @coo-quack/calc-mcp@latest

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