Cruncher

Cruncher: The Scientific Calculator MCP Server

A powerful scientific calculator for your AI assistant, built as a Model Context Protocol (MCP) server. Cruncher allows compatible AI clients (like Claude Desktop) to perform complex mathematical calculations, handle memory, perform statistical analysis, and access scientific constants with a simple, secure, and standardized interface.

🌟 The Purity Promise (Zero Dependencies)

Cruncher is built as a highly educational, extremely lightweight tool. It accomplishes powerful features without pulling in any heavy external libraries (no mathjs, no zod, no @modelcontextprotocol/sdk). Everything is handled using native Node.js capabilities:

• Safe Expression Evaluation: Instead of relying on mathjs or dangerous eval(), Cruncher uses new Function() guarded by a strict whitelist Regex that guarantees only numbers and math operators can pass.
• Input Validation: Instead of heavy schema libraries like Zod, a custom recursive validation function rigidly enforces AI inputs against JSON Schemas directly.
• Timeout Protection: Instead of complex process managers, it leverages Node.js worker_threads to spawn calculations. If an AI requests a multi-million loop factorial, the main thread easily terminates the worker after a strict timeout (default 3 seconds). This timeout is configurable via the CRUNCHER_TIMEOUT environment variable (in milliseconds), ensuring the server remains responsive even during heavy computational loads.
• Floating-Point Accuracy: Instead of using decimal.js, it solves the classic JS math error (0.1 + 0.2 = 0.30000000000000004) via dynamic integer-scaling logic under the hood.

📚 An Educational Approach to MCP

This project serves as an excellent learning resource for developers looking to understand the Model Context Protocol (MCP) deeply. Because it deliberately avoids using the official @modelcontextprotocol/sdk, the entire implementation of the MCP protocol, JSON-RPC message handling, input validations, and error formatting is exposed in plain JavaScript.

Reading through cruncher.js provides unparalleled, transparent insight into exactly how an MCP server communicates over stdio, parses incoming requests (initialize, tools/list, tools/call), and responds back to the AI client-demystifying the "magic" that SDKs usually hide away.

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that allows AI applications to securely connect with external data sources and tools. Think of it as a universal API for AI. By implementing Cruncher as an MCP server, any AI that understands MCP can instantly gain powerful, built-in calculator capabilities without custom integrations.

✨ Features

Cruncher provides a comprehensive set of calculator functions built completely from scratch without heavy dependencies:

• Robust Architecture:
• Zero Dependencies: Relies purely on Node.js standard libraries.
• Strict Input Validation: Custom schema validator prevents AI hallucinations and invalid data.
• Infinite Loop Protection: Utilizes Node.js worker_threads with a 3-second strict timeout to prevent complex calculations from freezing the server.
• Accurate Decimal Math: Uses an integer-scaling approach to prevent classic JS floating-point errors (e.g., 0.1 + 0.2 === 0.3).
• Tiered Tool Exposure: Three tiers (minimal, standard default, full) to optimize context token usage.
• Basic Arithmetic: Addition, Subtraction, Multiplication, Division, Modulo.
• Expression Evaluation: Safely compute entire plain-text math strings (e.g. (5 + 3) * 10 / 2).
• Power & Roots: Exponentiation (a^b), Square Root.
• Number Theory: Factorial (n!).
• Trigonometry: Sine, Cosine, Tangent, Arcsine (asin), Arccosine (acos), and Arctangent (atan) (with support for degrees and radians).
• Logarithms: Base-10 Logarithm and Natural Logarithm (ln).
• Statistical Functions: Sum, Average, Median, Min, Max, Range, Count, Variance, and Standard Deviation for arrays of numbers.
• Percentage Functions: Percentage-of, percentage-change, and reverse-percentage calculations.
• Unit Conversion: 80+ conversions across 8 categories (length, weight, temperature, area, volume, time, speed, digital_storage).
• Convenience Functions: Absolute Value.
• Constants: Easy access to Math (pi, e, tau, phi, sqrt2, euler_mascheroni), Physics (c, g, G, h, k, R), and Chemistry constants (NA, e_charge, m_e, m_p).
• Memory Functions: M+, M-, MR (Memory Recall), and MC (Memory Clear) - full tier only.

🚀 Installation & Usage

Get Cruncher up and running with Claude Desktop in just a few minutes.

Step 1: Prerequisites

Ensure you have Node.js (version 18.0.0 or newer) installed on your system. You can download it from nodejs.org.

Step 1: Quick Start with npm

Recommended: Install via npm and use directly:

npx @slbdn/cruncher-mcp

This downloads and runs the latest version automatically.

Step 2: Configure Claude Desktop

Recommended: Use the npm package for automatic updates:

{

"mcpServers": { "cruncher": { "command": "npx", "args": ["-y", "@slbdn/cruncher-mcp"] } } }

Step 3: Manual File (Alternative)

If you prefer to download the file manually instead:

1. Download the cruncher.js file directly from GitHub.
2. Place it in a permanent location (e.g., C:\mcp-servers\cruncher.js or /home/user/mcp-servers/cruncher.js).
3. Locate the Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

1. Add the server configuration pointing to your downloaded file:

json { "mcpServers": { "cruncher": { "command": "node", "args": ["C:/Users/YOUR_USERNAME/mcp-servers/cruncher.js"], "env": { "CRUNCHER_TOOL_SET": "standard" } } } }

Note for macOS/Linux Users: Use a POSIX-style path, e.g., "/home/YOUR_USERNAME/mcp-servers/cruncher.js". Make sure your node executable is in your system's PATH.

Step 4: Start Calculating!

1. Save the configuration file and completely quit the Claude Desktop app.
2. Restart Claude Desktop. It will automatically connect to the Cruncher server.
3. Start asking questions!

OpenWebUI (Formerly Ollama WebUI)

OpenWebUI natively supports connecting to stdio MCP servers.

Option A: Using npm package

1. Go to Admin Panel > Settings > Tools > MCP Servers.
2. Click Add Server.
3. Name it "Cruncher", select Command and enter npx, set Args to @slbdn/cruncher-mcp.

Option B: Using downloaded file

1. Go to Admin Panel > Settings > Tools > MCP Servers.
2. Click Add Server.
3. Name it "Cruncher", select stdio, use node as the command, and /path/to/cruncher.js as the argument.

Cursor IDE

You can give Cursor's built-in AI the ability to run math and calculate hashes.

Option A: Using npm package

1. Open Cursor Settings (gear icon) > Features > MCP Servers.
2. Click + Add New MCP Server.
3. Set Type to command, Name to cruncher, and Command to npx @slbdn/cruncher-mcp.

Option B: Using downloaded file

1. Open Cursor Settings (gear icon) > Features > MCP Servers.
2. Click + Add New MCP Server.
3. Set Type to command, Name to cruncher, and Command to node /path/to/cruncher.js.

Cline (VS Code Extension)

If you use Cline for agentic coding in VS Code, open the MCP configuration file (cline_mcp_settings.json) and add:

Option A: Using npm package

{

"mcpServers": { "cruncher": { "command": "npx", "args": ["-y", "@slbdn/cruncher-mcp"] } } }

Option B: Using downloaded file

{

"mcpServers": { "cruncher": { "command": "node", "args": ["/path/to/cruncher.js"], "env": { "CRUNCHER_TOOL_SET": "standard" } } } }

Goose (Terminal Agent)

Goose is a lightweight, terminal‑based AI assistant that fully supports MCP.

Option A: Using npm package

1. Edit ~/.goose/config.yaml (or the local project config).
2. Add a new server entry:

mcpServers:

cruncher: command: npx args:

• -y
• "@slbdn/cruncher-mcp"

Option B: Using downloaded file

1. Edit ~/.goose/config.yaml (or the local project config).
2. Add a new server entry:

mcpServers:

cruncher: command: node args:

• "/path/to/cruncher.js" env: CRUNCHER_TOOL_SET: "standard"

3. Restart Goose. You can now ask Goose to run calculations like `evaluate_expression` or `median` directly.

Zed Editor (AI Pane)

Zed's built‑in AI pane supports MCP connections.

Option A: Using npm package

1. Open Settings → AI → MCP Servers.
2. Click Add Server and fill in:

• Name: cruncher
• Command: npx
• Args: @slbdn/cruncher-mcp

1. Save. The Zed AI can now call Cruncher for precise arithmetic and statistics.

Option B: Using downloaded file

1. Open Settings → AI → MCP Servers.
2. Click Add Server and fill in:

• Name: cruncher
• Command: node
• Args: /absolute/path/to/cruncher.js
• Env (optional): CRUNCHER_TOOL_SET=standard

1. Save. The Zed AI can now call Cruncher for precise arithmetic and statistics.

LM Studio (Local LLM + MCP)

LM Studio runs LLMs entirely offline and now includes an MCP client.

Option A: Using npm package

1. Open Settings → MCP in LM Studio.
2. Click Add Server and provide:

• Executable: npx
• Arguments: @slbdn/cruncher-mcp

1. Confirm. Your private model can now offload math to Cruncher without any network traffic.

Option B: Using downloaded file

1. Open Settings → MCP in LM Studio.
2. Click Add Server and provide:

• Executable: node
• Arguments: /absolute/path/to/cruncher.js
• Environment (optional): CRUNCHER_TOOL_SET=standard

1. Confirm. Your private model (e.g., Llama 3, DeepSeek-V2) can now offload math to Cruncher without any network traffic.

LibreChat Configuration

If you're using LibreChat, you can add the following configuration to your librechat.yaml file:

Option A: Using npm package

  cruncher:

type: stdio command: npx args:

• -y
• "@slbdn/cruncher-mcp"

Option B: Using downloaded file

  cruncher:

type: stdio command: node args:

• "/opt/mcp/cruncher.js" env: CRUNCHER_TIMEOUT: "5000"

Example Questions for Claude

"What is the angle in degrees whose sine is 0.5?"

"Calculate the average, median, and range of these numbers: [15, 22, 8, 41, 19, 30]"

"What is 2 raised to the power of 10?"

"What is the standard deviation of [10, 12, 8, 14, 6]?"

"What is 15% of 240?"

"A stock went from $50 to $75. What's the percentage change?"

"What is the variance of test scores [85, 92, 78, 90, 88]?"

"Calculate the range of values in [3, 7, 2, 9, 1]"

"Evaluate the expression: sin(pi/4) + sqrt(16) + log10(100)"

"