SageMath MCP Server
by XBP-Europe
README.md
# SageMath MCP Server
<!-- mcp-name: io.github.XBP-Europe/sagemath-mcp -->
[](https://github.com/XBP-Europe/sagemath-mcp/actions/workflows/ci.yml)
[](https://github.com/XBP-Europe/sagemath-mcp/actions/workflows/codeql.yml)
[](https://github.com/XBP-Europe/sagemath-mcp/actions/workflows/audit.yml)
[](https://github.com/XBP-Europe/sagemath-mcp/actions/workflows/fuzz.yml)
[](https://github.com/XBP-Europe/sagemath-mcp/releases/latest)
[](https://pypi.org/project/sagemath-mcp/)
[](https://anaconda.org/conda-forge/sagemath-mcp)
[](https://github.com/XBP-Europe/sagemath-mcp/pkgs/container/sagemath-mcp)
[](LICENSE)
[](https://pypi.org/project/sagemath-mcp/)
[](https://modelcontextprotocol.io/)
[](https://gofastmcp.com/)
[](https://www.sagemath.org/)
[](https://docs.astral.sh/ruff/)
[](https://mypy-lang.org/)
[](https://github.com/XBP-Europe/sagemath-mcp/actions/workflows/ci.yml)
[](doctest-corpus-stats.md)
[](https://pypi.org/project/sagemath-mcp/)
[](https://registry.modelcontextprotocol.io/)
[](https://glama.ai/mcp/servers/XBP-Europe/sagemath-mcp)
[](https://github.com/XBP-Europe/sagemath-mcp/blob/main/SECURITY.md#verifying-a-release)
[](https://github.com/XBP-Europe/sagemath-mcp/blob/main/SECURITY.md#verifying-a-release)
[](https://github.com/XBP-Europe/sagemath-mcp/blob/main/.github/workflows/release.yml)
[](https://scorecard.dev/viewer/?uri=github.com/XBP-Europe/sagemath-mcp)
[](https://doi.org/10.5281/zenodo.22939422)
[](https://github.com/XBP-Europe/sagemath-mcp/blob/main/.github/dependabot.yml)
[](https://github.com/XBP-Europe/sagemath-mcp/commits/main)
A [Model Context Protocol](https://modelcontextprotocol.io/) server that gives an
LLM a sandboxed mathematical subset of [SageMath](https://www.sagemath.org/) —
symbolic calculus, number theory, linear algebra, ODEs, plotting, combinatorics,
graphs, groups, elliptic curves, and more. Each MCP session gets a dedicated Sage
worker process, so variables, functions, and assumptions **persist across tool
calls**. It ships **40 MCP tools**, one of which — `verify_claim` — re-checks a
stated result through a proof ladder and answers `proved` / `refuted` /
`supported` / `undecided` with its evidence.
Caller code is **deny-by-default**: the full breadth of Sage mathematics is
reachable, but imports, the external CAS interfaces, and the file / display /
persistence primitives are not. The policy accepts **98.9% of SageMath's own
438,124 documented doctest examples** (4,259 in-scope refusals, every one
attributed to a named rule; 98.9% of 433,687 on the passagemath runtime) while
refusing the rest — measured on every CI run (see [Security](#security)).
Full manual: **[USAGE.md](USAGE.md)** — the tools and their parameters, how code
is interpreted, and the security model in depth.
## Install & run
**Recommended — pip, with the [passagemath](https://github.com/passagemath/passagemath) Sage runtime:**
```bash
pip install "sagemath-mcp[passagemath]" # on Python 3.12; ~1 GB, no Docker, no Sage build
sagemath-mcp # stdio (default)
sagemath-mcp --transport streamable-http --port 8314 # HTTP on 127.0.0.1
```
or, with [uv](https://docs.astral.sh/uv/) and nothing installed permanently,
`uvx --python 3.12 --from "sagemath-mcp[passagemath]" sagemath-mcp`. This is the
route every client install below takes.
Use Python 3.12 for this extra; the `uvx` line asks for it, and uv downloads it
when the machine has none. 3.12 is the version CI tests it on, and the newest
for which every dependency ships a wheel: on 3.13 and later `memory-allocator`
is compiled from source, which needs a C compiler. Without `--python`, uv picks
its own newest Python (3.15 at the time of writing), and the install fails there.
passagemath is a pip-installable, modularized SageMath. `from sage.all import *`
and the worker run unmodified; the server detects the runtime at import and
loads the matching security artifacts, so the deny-by-default policy is
equivalent on both. It is pinned exactly (`passagemath-standard==10.8.13`) and
exercised by its own CI lane — the whole suite plus the doctest-corpus sweep
against the pin — so a pin bump is verified end to end before it ships, and the
last two releases passed that gate on first try
([docs/passagemath_evaluation.md](docs/passagemath_evaluation.md)).
macOS and Linux; native Windows support is partial, so on Windows use the
container or WSL.
**A pip install runs with your own privileges.** The security policy refuses
code that reaches outside mathematics, but it is not an operating-system
boundary ([SECURITY.md](SECURITY.md#security-model)). That suits your own client
on your own machine. For untrusted input, a shared host or multi-tenant use, run
the container.
**For isolation — the container image (SageMath is baked in):**
```bash
docker run --rm \
--read-only --tmpfs /tmp:rw,size=512m --tmpfs /home/sage/.sage:rw,size=256m \
--cap-drop ALL --security-opt no-new-privileges --pids-limit 256 --memory 4g \
-p 127.0.0.1:8314:8314 \
ghcr.io/xbp-europe/sagemath-mcp:latest
```
Those flags are the hardening the server expects; the port is published on
loopback deliberately — the server executes code and authenticates nobody.
`docker compose up --build` applies the same hardening from one reviewed file.
Released images are signed with Cosign and carry SLSA provenance and an SPDX
SBOM as registry attestations; the PyPI files carry PEP 740 attestations.
[DISTRIBUTION.md](DISTRIBUTION.md#verifying-signatures-provenance-and-sboms)
shows how to verify each.
**On arm64 (Apple silicon, Graviton): the passagemath image.** The monolithic
image above is published for `linux/amd64` only, so on arm64 it runs under
emulation. The same server on the passagemath runtime ships as a native
`linux/amd64` + `linux/arm64` image, with the same hardening flags, UID and
security policy:
```bash
docker run --rm \
--read-only --tmpfs /tmp:rw,size=512m --tmpfs /home/sage/.sage:rw,size=256m \
--cap-drop ALL --security-opt no-new-privileges --pids-limit 256 --memory 4g \
-p 127.0.0.1:8314:8314 \
ghcr.io/xbp-europe/sagemath-mcp:latest-passagemath
```
Every release tag has a `-passagemath` twin (`vX.Y.Z-passagemath`), each
architecture is smoke-tested natively before it is published, and the index is
signed and attested like the primary image. It is the optional image on amd64,
where the monolithic one stays primary.
**One click in a desktop MCP host (Claude Desktop and friends):** download
`sagemath-mcp-<version>.mcpb` from the
[latest release](https://github.com/XBP-Europe/sagemath-mcp/releases/latest) and
open it. The bundle is about 27 KB; your host installs the server *and*
a Sage runtime with uv on first launch, which is roughly a 1 GB download once.
macOS and Linux — native Windows is excluded because passagemath's Windows
support is partial. A bundle is a local install with your own privileges; for
untrusted or multi-tenant use run the container instead.
**With a Sage you already have (PyPI):**
```bash
pip install sagemath-mcp
sagemath-mcp # stdio (default)
sagemath-mcp --transport streamable-http --port 8314 # HTTP on 127.0.0.1
```
This needs a working SageMath on the host: `sage` on your `PATH`, or in the same
environment as the server. A Sage inside a container is out of reach of a server
on the host; without a Sage of your own, use the `[passagemath]` extra above.
**From conda-forge (Linux and macOS, next to conda-forge's Sage):**
```bash
conda install -c conda-forge "sagemath-mcp>=0.9.4" sage
sagemath-mcp
```
The version floor matters: earlier releases cannot start a worker on
conda-forge's `sage`, and without it the solver may pick one. That `sage` is 10.9, one release behind the 10.10 the
security artifacts are generated from, so names 10.10 added are unavailable and
nothing outside the allowlist is admitted.
Source install, Docker Compose, and the Kubernetes Helm chart are in
**[USAGE.md](USAGE.md)**.
## Connect an MCP client
One command or one click each. Every route below installs a Sage runtime
alongside the server, so there is nothing else to set up.
[](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522sagemath%2522%252C%2522command%2522%253A%2522uvx%2522%252C%2522args%2522%253A%255B%2522--python%2522%252C%25223.12%2522%252C%2522--from%2522%252C%2522sagemath-mcp%255Bpassagemath%255D%2522%252C%2522sagemath-mcp%2522%255D%257D)
[](https://cursor.com/en/install-mcp?name=sagemath&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLXB5dGhvbiIsIjMuMTIiLCItLWZyb20iLCJzYWdlbWF0aC1tY3BbcGFzc2FnZW1hdGhdIiwic2FnZW1hdGgtbWNwIl19)
**Claude Desktop** — download `sagemath-mcp-<version>.mcpb` from the
[latest release](https://github.com/XBP-Europe/sagemath-mcp/releases/latest) and
open it. One click, no config file.
**Claude Code** — as a plugin from this repository's marketplace, inside a session:
```
/plugin install sagemath-mcp --marketplace XBP-Europe/sagemath-mcp
```
or as a plain MCP server:
```bash
claude mcp add sagemath -- uvx --python 3.12 --from "sagemath-mcp[passagemath]" sagemath-mcp
```
**Gemini CLI** — the repository is itself an extension:
```bash
gemini extensions install https://github.com/XBP-Europe/sagemath-mcp
```
**Codex CLI**
```bash
codex mcp add sagemath -- uvx --python 3.12 --from "sagemath-mcp[passagemath]" sagemath-mcp
```
Then ask for some mathematics — the [examples below](#try-it) are a good start.
Three things worth knowing. These need [uv](https://docs.astral.sh/uv/) on your
PATH, and the first launch downloads about 1 GB of Sage wheels, cached
afterwards. Already have `sage`? Drop `[passagemath]` from the specification and
it will use yours. Installed from conda-forge? Register the environment's own
executable, for example `claude mcp add sagemath -- ~/miniforge3/envs/sage/bin/sagemath-mcp`;
it finds the `sage` beside it without the environment being activated. And an install of any of these runs with your own privileges;
for untrusted or shared use, run the container and point the client at it.
Pinning a release, HTTP transport and the full client reference are in
[USAGE.md](USAGE.md#integrating-with-mcp-clients).
## Try it
Prompts a client can run once the server is connected:
- **Damped harmonic oscillator** — "Solve `x'' + 2·x' + 5·x = 0` with
`x(0)=1`, `x'(0)=0`, then verify the solution satisfies the ODE."
- **General relativity** — "On the hyperbolic upper half-plane with metric
`(dx² + dy²)/y²`, compute the Ricci scalar and confirm it is a constant
negative curvature."
- **Coupled two-tank system** — "Solve the linear ODE system for two mixing
tanks, then take the long-term limit of each concentration."
Each builds an object once and explores it across calls — the case for
`evaluate_sage` and its persistent session.
## The 40 tools
The math tools use SageMath as the backend; parameters and examples for the
most-used ones are in **[USAGE.md](USAGE.md#tool-reference)**.
| Category | Tools |
|----------|-------|
| **Core execution** | `evaluate_sage`, `evaluate_sage_streaming` |
| **Verification** | `verify_claim` |
| **Calculus** | `differentiate_expression`, `integrate_expression`, `limit_expression`, `series_expansion` |
| **Algebra** | `solve_equation`, `simplify_expression`, `expand_expression`, `factor_expression`, `calculate_expression`, `symbolic_sum` |
| **Linear algebra** | `matrix_multiply`, `matrix_operation` |
| **Differential equations** | `solve_ode` |
| **Number theory** | `number_theory_operation` |
| **Combinatorics** | `combinatorics_operation` |
| **Graph / group theory** | `graph_operation`, `group_operation` |
| **Elliptic curves / coding** | `elliptic_curve_operation`, `coding_theory_operation` |
| **Polynomials / boolean / geometry** | `polynomial_ring_operation`, `boolean_algebra_operation`, `geometry_operation` |
| **Statistics / probability** | `statistics_summary`, `distribution_operation` |
| **Visualization** | `plot_expression`, `plot3d_expression`, `plot_multi_expression` |
| **Numeric methods / vector calculus** | `find_root`, `vector_calculus_operation` |
| **Session control** | `reset_sage_session`, `interrupt_sage_session`, `cancel_sage_session` |
| **Named workspaces** | `start_sage_session`, `list_sage_sessions`, `stop_sage_session` |
| **Diagnostics** | `check_sage_health`, `lookup_sage_doc` |
Plus HTTP `/health` and `/ready` endpoints and 3 MCP resources (session
snapshots, monitoring metrics, doc links). Prefer `interrupt_sage_session` over
`cancel_sage_session` — it stops a computation while keeping the session's
variables.
## How it works
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Client (Claude Desktop, Gemini CLI, Codex CLI, ...) │
└───────────────────────────┬─────────────────────────────────┘
│ MCP protocol (stdio or HTTP)
▼
┌─────────────────────────────────────────────────────────────┐
│ app.py + tools/ --- FastMCP 4.x │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ 40 MCP Tools│ │ 3 Resources │ manager.py routes each │
│ └─────────────┘ └──────────────┘ client to its worker │
└───────────────────────────┬─────────────────────────────────┘
▼ one subprocess per session
┌─────────────────────────────────────────────────────────────┐
│ _sage_worker.py --- allowlist.py + security.py │
│ AST validation, then exec() in a persistent namespace │
│ (vars, functions and classes survive across calls) │
└─────────────────────────────────────────────────────────────┘
```
**Request flow:** MCP client → a tool in `tools/` →
`SageSessionManager.get()` → `SageSession.evaluate()` → JSON request to
the `_sage_worker.py` subprocess → AST validation → `exec()` in the persistent
namespace → JSON response.
- **Process isolation** — each session runs Sage in its own subprocess; a crash
or timeout in one cannot affect another.
- **Stateful sessions** — variables, functions, and assumptions persist across
calls, enabling multi-step workflows.
- **Deny-by-default** — a name is refused unless the generated allowlist offers
it or the caller's own code bound it. A helper a future SageMath adds is
refused until someone reviews it, rather than reachable the day it lands.
## Security
The AST validator is **defence in depth against accidents and casual misuse — it
is not a boundary against determined adversarial code.** **The container is the
security boundary.** The server has **no authentication**, so every default is
loopback: `--host` defaults to `127.0.0.1`, the default transport is stdio, and
Compose / Helm keep the endpoint off the network. Put something that
authenticates in front of it before exposing it.
What the policy enforces: an **allowlist** (caller code may read only a name the
server offers or the caller itself bound); **no imports** by default; `eval` /
`exec` / `compile` and runtime string evaluation blocked; dunder access blocked;
the external CAS interfaces and every file / network / persistence primitive
removed from the namespace, by provenance rather than by name; and the `sage`
package tree closed to caller code, so a helper is reached by its own name or
not at all. The container adds
a read-only root, dropped capabilities, `no-new-privileges`, the default
seccomp profile, and memory ceilings. Compose adds a fork (PID) ceiling;
Kubernetes has no per-pod equivalent in the pod spec, so on the chart that is
the node's `podPidsLimit` rather than something the chart can set.
Full threat model and the complete blocked / allowed tables:
**[SECURITY.md](SECURITY.md)** and
[USAGE.md § Security model](USAGE.md#security-model).
## Docs & more
- **[USAGE.md](USAGE.md)** — the full manual: every tool, how code is
interpreted, deployment, and the security model.
- **[docs/mcp_quickstart.md](docs/mcp_quickstart.md)** — a first-session walk-through.
- **[CHANGELOG.md](CHANGELOG.md)** · **[ROADMAP.md](ROADMAP.md)** ·
**[CONTRIBUTING.md](CONTRIBUTING.md)** · **[SECURITY.md](SECURITY.md)** ·
**[SUPPORT.md](SUPPORT.md)** — what "supported" means, release cadence,
where to ask. **[PRIVACY.md](PRIVACY.md)** — what the server keeps (nothing
leaves the machine it runs on).
## Requirements
Python 3.12+ and a SageMath runtime (the container image bundles SageMath 10.10;
otherwise `sage` on `PATH`, or the `[passagemath]` extra). Built on
[FastMCP 4.x](https://gofastmcp.com/).
## Contributing
Issues and pull requests welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Run
`make lint`, `make typecheck` and `make test` before pushing
(`git config core.hooksPath .githooks` wires the pre-push check). Roadmap and open work: [ROADMAP.md](ROADMAP.md).
Questions go to [GitHub Discussions](https://github.com/XBP-Europe/sagemath-mcp/discussions);
[SUPPORT.md](SUPPORT.md) says what to expect.
## Citing
If this server is part of published work, cite it via
[CITATION.cff](CITATION.cff) — GitHub renders it as *Cite this repository* in the
sidebar, with APA and BibTeX. Cite SageMath itself as well; it does the
mathematics.
## License
MIT — see [LICENSE](LICENSE). SageMath itself is GPL-2.0-or-later and is used as a
separate runtime; no SageMath source is redistributed in this repository.
TDQS
B3.2/5.0
Scored across 40 tools
Disambiguation3/5
Most tools have distinct domain prefixes (calculus, linear algebra, number theory), but several boundaries blur: evaluate_sage vs evaluate_sage_streaming vs calculate_expression all execute/evaluate Sage code, and factor_expression overlaps with number_theory_operation's integer factorization. The 'operation' suffix on eleven tools makes their exact scope harder to distinguish at a glance.
Naming Consistency3/5
The majority follow verb_noun (solve_equation, integrate_expression, start_sage_session), but there are notable deviations: the eleven 'X_operation' tools are noun_noun, matrix_multiply is noun_verb, and series_expansion/symbolic_sum are noun phrases. All names are snake_case and readable, so the inconsistency is moderate rather than chaotic.
Tool Count2/5
Forty tools is well above the 25+ threshold and will burden an agent's tool-selection step, even though SageMath's breadth justifies many of them. Several 'operation' tools could be consolidated (e.g., one linear_algebra tool) without losing clarity.
Completeness4/5
The surface covers calculus, algebra, linear algebra, number theory, combinatorics, graph/group theory, elliptic curves, coding theory, geometry, statistics, distributions, plotting, and session management. Missing dedicated tools like Laplace transforms or matrix addition are reachable through evaluate_sage, so there are no dead ends; only minor gaps remain.
Maintenance
ActivityActive
ResponsivenessUnresponsive