![Logo](https://s3.devantage.com.br/devantage-public/logo-100x100.png)

# MCP Calculator

A modern [Model Context Protocol](https://modelcontextprotocol.io) server for
mathematical calculations.
Exposes 13 tools (6 core + 7 specialized) with high-precision arithmetic, a safe expression evaluator, statistics, unit conversion, and financial math.

## Requirements

- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (or Docker, for the containerized setup)

## Installation

```bash
uv venv

uv pip install -e ".[dev]"
```

## Running

The server supports two transports, selected via the `MCP_TRANSPORT` environment variable (see [Configuration](#configuration)).

### STDIO

The server speaks MCP over **stdio** by default (the transport used by most MCP
clients such as Claude Desktop and Claude Code):

```bash
source .venv/bin/activate

mcp-calculator
```

### Streamable HTTP

To serve over **streamable HTTP** instead:

```bash
source .venv/bin/activate

MCP_TRANSPORT=http mcp-calculator
```

The HTTP endpoint is then available at `http://0.0.0.0:8080/mcp/`.

### Docker

Build the image and run it in HTTP mode (the image defaults to HTTP on port 8080):

```bash
docker build -t mcp-calculator .

docker run --rm -p 8080:8080 mcp-calculator
```

Override any setting at runtime with `-e`, e.g. a different port:

```bash
docker run --rm -p 9000:9000 -e MCP_PORT=9000 mcp-calculator
```

## Configuration

| Variable        | Default   | Description                                                         |
| --------------- | --------- | ------------------------------------------------------------------- |
| `MCP_TRANSPORT` | `stdio`   | Transport to use: `stdio` or `http` (streamable HTTP).              |
| `MCP_HOST`      | `0.0.0.0` | Host/interface to bind when using HTTP. Use `0.0.0.0` to expose it. |
| `MCP_PORT`      | `8080`    | Port to listen on when using HTTP.                                  |

## Available Tools

### Core

| Tool                  | Description                                                                           |
| --------------------- | ------------------------------------------------------------------------------------- |
| `basic_math`          | add / subtract / multiply / divide with decimal precision (0-15)                      |
| `advanced_math`       | trig, inverse trig, log/ln, sqrt, abs, factorial, exp, pow                            |
| `expression_eval`     | evaluate expressions with variables, constants, and functions                         |
| `statistics_analysis` | mean, median, mode, std_dev, variance, percentile, range, skewness, kurtosis, summary |
| `unit_conversion`     | length, weight, temperature, volume, area                                             |
| `financial_calc`      | simple/compound interest, loan payment, ROI, present/future value                     |

### Specialized

| Tool                   | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `stats_summary`        | full statistical overview of a dataset           |
| `percentile`           | a specific percentile (0-100) of a dataset       |
| `batch_conversion`     | convert many values between units at once        |
| `npv`                  | Net Present Value of cash flows                  |
| `irr`                  | Internal Rate of Return (Newton-Raphson)         |
| `loan_comparison`      | compare loans, return the lowest monthly payment |
| `investment_scenarios` | compare investments, return the highest return   |

## Development

### Testing

Run the test suite with:

```bash
pytest
```

## License

[MIT](./LICENSE)