# precision-math-mcp

**LLMs can't do math.** They predict tokens, not compute answers. Ask an LLM to multiply large numbers or solve equations, and you might get confident-sounding wrong answers.

This MCP server fixes that by giving your LLM a real calculator. It's powered by [math.js](https://mathjs.org/), a battle-tested math library with 14k+ GitHub stars, handling everything from basic arithmetic to symbolic calculus.

All expressions use **math.js syntax** - see [math.js documentation](https://mathjs.org/docs/) for full expression reference.

## Features

- **6 Mathematical Tools**:
  - `calculate` - Evaluate mathematical expressions
  - `simplify` - Simplify algebraic expressions
  - `derivative` - Compute symbolic derivatives
  - `solve` - Solve equations for variables
  - `format` - Format numbers with precision/notation
  - `convert` - Convert between units

- **3 Transport Modes**:
  - `stdio` - Standard I/O (default, for Claude Desktop)
  - `http` - Streamable HTTP transport
  - `sse` - Server-Sent Events (backwards compatibility)

## Quick Start

Run directly without installing (requires Bun, npm, yarn, or pnpm):

```bash
# Using bunx (recommended)
bunx -y @nerdo/precision-math-mcp

# Using npx
npx -y @nerdo/precision-math-mcp

# Using yarn
yarn dlx @nerdo/precision-math-mcp

# Using pnpm
pnpm dlx @nerdo/precision-math-mcp
```

## Installation

### Global Install

```bash
# Using bun
bun add -g @nerdo/precision-math-mcp

# Using npm
npm install -g @nerdo/precision-math-mcp

# Using yarn
yarn global add @nerdo/precision-math-mcp

# Using pnpm
pnpm add -g @nerdo/precision-math-mcp
```

Then run with:

```bash
precision-math-mcp
```

### Local Development

```bash
git clone https://github.com/nerdo/precision-math-mcp
cd precision-math-mcp
bun install
bun run src/index.ts
```

## Usage

### Transport Modes

```bash
# Stdio mode (default)
bunx -y @nerdo/precision-math-mcp --stdio

# HTTP mode
PORT=3141 bunx -y @nerdo/precision-math-mcp --http

# HTTP mode with authentication
PORT=3141 MCP_AUTH_TOKEN=your-secret bunx -y @nerdo/precision-math-mcp --http
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 3141 | HTTP server port |
| `MCP_AUTH_TOKEN` | (none) | Optional auth token for HTTP |
| `MCP_TRANSPORT` | stdio | Transport mode: stdio, http, sse |
| `DESCRIPTION_MODE` | mandatory | Tool description mode: mandatory (AI must use for all math) or relaxed (optional use) |

## MCP Client Configuration

### Claude Desktop

Add to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "precision-math": {
      "command": "bunx",
      "args": ["-y", "@nerdo/precision-math-mcp"]
    }
  }
}
```

Or using npx:

```json
{
  "mcpServers": {
    "precision-math": {
      "command": "npx",
      "args": ["-y", "@nerdo/precision-math-mcp"]
    }
  }
}
```

### Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "precision-math": {
      "command": "bunx",
      "args": ["-y", "@nerdo/precision-math-mcp"]
    }
  }
}
```

## Tool Examples

### calculate

Evaluate mathematical expressions with optional variables.

```json
{
  "name": "calculate",
  "arguments": {
    "expression": "sqrt(a^2 + b^2)",
    "scope": { "a": 3, "b": 4 }
  }
}
// Returns: { "result": "5", "type": "number" }
```

Supports:
- Basic arithmetic: `2 + 2 * 3` → `8`
- Functions: `sin(pi/4)`, `log(100)`, `factorial(5)`
- Complex numbers: `sqrt(-1)` → `i`
- Matrices: `[[1,2],[3,4]] * [[1,0],[0,1]]`
- Units: `2 inch to cm` → `5.08 cm`

### simplify

Simplify algebraic expressions.

```json
{
  "name": "simplify",
  "arguments": {
    "expression": "2x + 3x - x"
  }
}
// Returns: { "result": "4 * x" }
```

### derivative

Compute symbolic derivatives.

```json
{
  "name": "derivative",
  "arguments": {
    "expression": "x^3 + 2*x",
    "variable": "x"
  }
}
// Returns: { "result": "3 * x ^ 2 + 2", "simplified": "3 * x ^ 2 + 2" }
```

### solve

Solve equations for a variable.

```json
{
  "name": "solve",
  "arguments": {
    "equation": "x^2 - 4 = 0",
    "variable": "x"
  }
}
// Returns: { "solutions": ["2", "-2"], "type": "exact" }
```

### format

Format numbers with specific precision or notation.

```json
{
  "name": "format",
  "arguments": {
    "value": "pi",
    "precision": 4
  }
}
// Returns: { "result": "3.142" }
```

### convert

Convert between units.

```json
{
  "name": "convert",
  "arguments": {
    "value": "100 km/h",
    "toUnit": "m/s"
  }
}
// Returns: { "result": "27.77777777777778 m / s", "numericValue": 27.77777777777778 }
```

## Testing

```bash
# Run all tests
bun test

# Run specific test file
bun test tests/tools/calculate.test.ts
```

## Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector bun run src/index.ts
```

Opens the MCP Inspector at http://localhost:6274 where you can:
- View all available tools
- Invoke tools with custom arguments
- See JSON-RPC communication logs

## Development

```bash
# Type check
bunx tsc --noEmit

# Run in watch mode
bun --watch run src/index.ts
```

## License

MIT