# math-mcp

[![CI](https://github.com/AbderY/math-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/AbderY/math-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/math-mcp-ay.svg)](https://pypi.org/project/math-mcp-ay/)

A small [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server
that gives an LLM a set of reliable math tools — expression evaluation,
statistics, number theory, linear algebra, and symbolic math — instead of
asking it to do arithmetic in its head.

Every tool runs real, deterministic code. The expression evaluator is
**sandboxed**: it parses input into an AST and only allows a whitelist of
operators, constants, and functions. It never calls Python's `eval`. Symbolic
tools parse input with SymPy's tokenizing parser (also no `eval`).

## Tools

### Numeric & number theory

| Tool | Description |
| --- | --- |
| `evaluate` | Evaluate an expression like `sqrt(2) * sin(pi / 4)`. Supports `+ - * / // % **`, parentheses, constants (`pi`, `e`, `tau`) and functions (`sqrt`, `sin`, `log`, `factorial`, `gcd`, `hypot`, …). |
| `descriptive_statistics` | Count, sum, min, max, mean, median, variance and standard deviation (population and sample) of a list of numbers. |
| `is_prime` | Test whether an integer is prime. |
| `prime_factorization` | Factor a positive integer into primes with exponents. |
| `gcd_lcm` | Greatest common divisor and least common multiple of two or more integers. |
| `solve_quadratic` | Roots of `a·x² + b·x + c = 0`, real or complex, with the discriminant. |
| `convert_base` | Convert an integer between bases 2–36. |

### Linear algebra

Matrices are lists of rows, e.g. `[[1, 2], [3, 4]]`.

| Tool | Description |
| --- | --- |
| `matrix_multiply` | Matrix product `A @ B`. |
| `matrix_transpose` | Transpose of a matrix. |
| `matrix_determinant` | Determinant of a square matrix. |
| `matrix_inverse` | Inverse of a square, non-singular matrix. |
| `solve_linear_system` | Solve `A x = b` for `x`. |

### Symbolic (SymPy)

| Tool | Description |
| --- | --- |
| `simplify_expression` | Simplify, e.g. `sin(x)**2 + cos(x)**2` → `1`. |
| `expand_expression` | Expand, e.g. `(x + 1)**2` → `x**2 + 2*x + 1`. |
| `factor_expression` | Factor, e.g. `x**2 - 1` → `(x - 1)*(x + 1)`. |
| `differentiate` | Derivative w.r.t. a variable (any order). |
| `integrate` | Indefinite integral w.r.t. a variable. |
| `definite_integral` | Definite integral over `[lower, upper]` (bounds may be `oo`). |
| `limit` | Limit as a variable approaches a point (`oo` allowed; left/right/two-sided). |
| `taylor_series` | Taylor series about a point, up to N terms. |
| `solve_symbolic_equation` | Solve an equation, e.g. `x**2 = 4` → `["-2", "2"]`. |

## Resources & prompts

Beyond tools, the server exposes:

- **Resources** — mathematical constants to 50 digits: `math://constants`
  (an index) and `math://constants/{name}` for `pi`, `e`, `tau`, `phi`
  (golden ratio) and `gamma` (Euler–Mascheroni).
- **Prompts** — reusable templates a client can offer to the user:
  `solve_step_by_step` and `solve_linear_system_prompt`.

## Install

Requires Python 3.10+.

Once published to PyPI (distribution name `math-mcp-ay`):

```bash
pip install math-mcp-ay
```

The import package is `math_mcp` and the command is `math-mcp` regardless of
the distribution name.

From source (for development):

```bash
git clone https://github.com/AbderY/math-mcp.git
cd math-mcp
pip install -e ".[dev]"
```

## Run

The server speaks MCP over stdio:

```bash
math-mcp
# or
python -m math_mcp
```

### Use with an MCP client

Add it to your client's MCP configuration. For example (Claude Desktop /
`claude_desktop_config.json`, or any MCP client that launches servers):

```json
{
  "mcpServers": {
    "math": {
      "command": "math-mcp"
    }
  }
}
```

If `math-mcp` is not on your `PATH`, use the interpreter form instead:

```json
{
  "mcpServers": {
    "math": {
      "command": "python",
      "args": ["-m", "math_mcp"]
    }
  }
}
```

## Examples

- `evaluate("2 ** 10 + factorial(5)")` → `1144.0`
- `descriptive_statistics([2, 4, 4, 4, 5, 5, 7, 9])` → mean `5.0`, `pstdev` `2.0`
- `prime_factorization(360)` → `2³ · 3² · 5`
- `solve_quadratic(1, -3, 2)` → roots `1.0` and `2.0`
- `convert_base("ff", 16, 2)` → `"11111111"`
- `matrix_inverse([[4, 7], [2, 6]])` → `[[0.6, -0.7], [-0.2, 0.4]]`
- `solve_linear_system([[1, 1], [1, -1]], [3, 1])` → `[2.0, 1.0]`
- `differentiate("x**3", "x", 2)` → `"6*x"`
- `definite_integral("exp(-x)", "x", "0", "oo")` → `"1"`
- `limit("sin(x)/x", "x", "0")` → `"1"`
- `taylor_series("exp(x)", "x", "0", 4)` → `"x**3/6 + x**2/2 + x + 1"`
- `solve_symbolic_equation("x**2 = 4")` → `["-2", "2"]`

## Development

```bash
pip install -e ".[dev]"
pytest
```

## Releasing to PyPI

Publishing is automated via GitHub Actions using
[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC),
so no API token is stored in the repo.

One-time setup on [pypi.org](https://pypi.org):

1. Create (or claim) the project name `math-mcp-ay`.
2. Under the project's *Publishing* settings, add a **trusted publisher**:
   - Owner: `AbderY`, repository: `math-mcp`
   - Workflow: `publish.yml`
   - Environment: `pypi`

Then, to release: bump the version in `pyproject.toml` and
`src/math_mcp/__init__.py`, tag it, and publish a GitHub Release. The
`publish.yml` workflow builds the sdist + wheel and uploads them to PyPI.

## License

[MIT](LICENSE)