mcp-calculator

An MCP server that wraps MathJS to give AI models a powerful calculate tool.
Supports stdio (Claude Desktop) and HTTP Streamable transports.

Installation

npm install
npm run build

Usage

Stdio mode (default)

node dist/index.js

HTTP mode

# default port 3000
node dist/index.js --http

# custom port
PORT=8080 node dist/index.js --http

# via environment variable
TRANSPORT=http node dist/index.js

Expression examples

Category	Expression	Result
Arithmetic	`2 + 3 * 4`	`14`
Fractions	`1/3 + 1/6`	`0.5`
Powers	`2^10`	`1024`
Trigonometry	`sin(pi / 4)`	`0.70710678118655`
Inverse trig	`acos(0)`	`1.5707963267949`
Logarithm	`log(1000, 10)`	`3`
Complex numbers	`(2 + 3i) * (1 - 2i)`	`8 - i`
Statistics	`mean(1, 2, 3, 4, 5)`	`3`
Matrix determinant	`det([1, 2; 3, 4])`	`-2`
Matrix multiply	`[1,2;3,4] * [5;6]`	`[[17],[39]]`
Unit conversion	`2 km to mile`	`1.2427423844747 mile`
Constants	`e ^ (i * pi) + 1`	`2.8327021... × 10^-15 + 0i` ≈ `0`

Docker

Pull and run the pre-built image from Docker Hub:

# stdio mode (pipe JSON-RPC over stdin/stdout)
docker run --rm -i bangbang93/mcp-calculator node dist/index.js

# HTTP mode on port 3000
docker run --rm -p 3000:3000 bangbang93/mcp-calculator

# custom port
docker run --rm -p 8080:8080 -e PORT=8080 bangbang93/mcp-calculator

Build locally:

docker build -t mcp-calculator .
docker run --rm -p 3000:3000 mcp-calculator

HTTP mode — usage examples

Once the server is running in HTTP mode (node dist/index.js --http), send JSON-RPC 2.0 requests with curl:

# Initialize a session
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# Call the calculate tool
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculate","arguments":{"expression":"sin(pi/4)"}}}'

Claude Desktop configuration

Add the following to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "calculator": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-calculator/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/mcp-calculator with the actual path where you cloned this repository.

Alternatively, use the Docker image so no local build is required:

{
  "mcpServers": {
    "calculator": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "bangbang93/mcp-calculator", "node", "dist/index.js"]
    }
  }
}

GitHub Copilot CLI

Add the server to your GitHub Copilot CLI MCP configuration (~/.config/github-copilot/mcp.json on Linux/macOS, %APPDATA%\GitHub Copilot\mcp.json on Windows):

{
  "mcpServers": {
    "calculator": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-calculator/dist/index.js"]
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "calculator": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "bangbang93/mcp-calculator", "node", "dist/index.js"]
    }
  }
}

After saving the config, the calculate tool is available to Copilot in any chat or inline suggestion session. You can also test it directly with gh copilot suggest:

$ gh copilot suggest "calculate sin(pi/4) using the calculator tool"

opencode

Add the server to your opencode configuration (~/.config/opencode/config.json):

{
  "mcp": {
    "calculator": {
      "type": "local",
      "command": ["node", "/absolute/path/to/mcp-calculator/dist/index.js"]
    }
  }
}

Or HTTP mode (start the server first with node dist/index.js --http):

{
  "mcp": {
    "calculator": {
      "type": "remote",
      "url": "http://localhost:3000"
    }
  }
}

Development

# Run TypeScript directly (no build step)
npm run dev

# HTTP mode during development
npm run dev:http

mcp-calculator

mcp-calculator

Installation

Usage

Stdio mode (default)

HTTP mode

Expression examples

Docker

HTTP mode — usage examples

Claude Desktop configuration

GitHub Copilot CLI

opencode

Development

Latest Blog Posts

MCP directory API