SageMath MCP Server

A Model Context Protocol server that gives an LLM a sandboxed mathematical subset of SageMath — 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.6% of SageMath's own 432,878 documented doctest examples while refusing the rest — measured on every CI run (see Security).

Full manual: USAGE.md — every tool's parameters and examples, how code is interpreted, and the security model in depth.

Install & run

Recommended — the container image (SageMath is baked in):

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.

From PyPI (bring your own Sage runtime):

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 — either sage on your PATH or the sagemath/sagemath Docker image.

A Sage runtime without the 3 GB image (passagemath, optional):

pip install "sagemath-mcp[passagemath]"    # ~1 GB, no Docker, no local Sage build
sagemath-mcp

A pip-installable, modularized fork of 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.9) and exercised by its own CI lane — the whole suite plus the doctest-corpus sweep against the pin — because passagemath's release QA has shipped broken backends (docs/passagemath_evaluation.md). It is the optional runtime; the monolithic image stays primary, and for untrusted or multi-tenant use run the container regardless of runtime — a pip install has your user's privileges, the container adds OS-level isolation.

Source install, Docker Compose, and the Kubernetes Helm chart are in USAGE.md.

Connect an MCP client

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "sagemath": { "command": "uv", "args": ["run", "sagemath-mcp"] }
  }
}

Claude Code, Codex CLI, Gemini CLI, and HTTP-transport setup are in USAGE.md.

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; full parameters and examples are in USAGE.md.

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 3.x                            │
│  ┌─────────────┐  ┌──────────────┐                          │
│  │ 40 MCP Tools│  │ 3 Resources  │   session.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_or_create() → 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. The container adds a read-only root, dropped capabilities, no-new-privileges, and fork / memory ceilings.

Full threat model and the complete blocked / allowed tables: SECURITY.md and USAGE.md § Security model.

Docs & more

• USAGE.md — the full manual: every tool, how code is interpreted, deployment, and the security model.
• docs/mcp_quickstart.md — a first-session walk-through.
• CHANGELOG.md · ROADMAP.md · CONTRIBUTING.md · SECURITY.md

Requirements

Python 3.12+ and a SageMath runtime (the container image bundles SageMath 10.9; otherwise sage on PATH, or the [passagemath] extra). Built on FastMCP 3.x.

Contributing

Issues and pull requests welcome — see CONTRIBUTING.md. Run make lint and make test before pushing (git config core.hooksPath .githooks wires the pre-push check). Roadmap and open work: ROADMAP.md.

License

MIT — see LICENSE. SageMath itself is GPL-2.0-or-later and is used as a separate runtime; no SageMath source is redistributed in this repository.