Calc MCP

Calc MCP demo

📖 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

bash

# 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

Terminal

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:

Code

/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`

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:

config.json

{
  "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:

Terminal

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

Or use in MCP client config:

config.json

{
  "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:

Terminal

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

bash

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:

bash

# ❌ 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