io.github.justice8096/sagemath-mcp-server

Official

by justice8096 · TypeScript

MCP server wrapping SageMath's full computer algebra system — 10 symbolic-math tools for LLMs.

Provides symbolic mathematics and computer algebra system tools for LLMs.

SageMath MCP Server

A Model Context Protocol server that exposes SageMath — a 100+ package computer algebra system — to LLM clients such as Claude. Where most "math MCPs" wrap a single library (SymPy, mathjs), this one subprocess-wraps the entire SageMath stack so the model has access to genuine symbolic mathematics, not arithmetic.

Why

LLMs are bad at exact arithmetic, brittle with multi-step algebra, and unreliable when symbolic manipulation matters. The right pattern is to keep the conceptual reasoning in the model and delegate mechanical computation to a tool — the same trick a person with dyscalculia uses with a calculator. SageMath gives you the broadest tool surface for that delegation: factoring, integration, eigenvalues, number theory, LaTeX rendering, and plotting all behind one interface.

Tools

Tool	Description
`sage_evaluate`	Run an arbitrary SageMath expression.
`sage_solve_equation`	Solve algebraic / transcendental equations symbolically.
`sage_differentiate`	Compute derivatives (any order, any variable).
`sage_integrate`	Indefinite and definite integrals.
`sage_simplify`	Simplify expressions (`default`, `full`, `trig`, `rational`).
`sage_factor`	Factor polynomials or integers.
`sage_matrix_ops`	Determinant, inverse, eigenvalues, rank, RREF, transpose over `QQ` / `RR` / `ZZ` / `CC`.
`sage_plot`	Plot an expression and return a base64 PNG.
`sage_latex_convert`	Convert a SageMath expression to LaTeX.
`sage_number_theory`	`is_prime`, `next_prime`, `factor`, `euler_phi`, `gcd`, `lcm`, `prime_range`, `sigma`, `moebius`.

All tools follow the same schema pattern (see src/schemas/common.ts).

Installation

The server needs either a local SageMath install or Docker available on the host so it can spawn a SageMath process.

Option 1: npm + local SageMath

bash

npm install -g @justice8096/sagemath-mcp-server
# requires `sage` on PATH — see https://doc.sagemath.org/html/en/installation/
sagemath-mcp

Option 2: Docker (no local SageMath required)

bash

docker compose up
# uses the official sagemath/sagemath image; the server runs inside the container

Option 3: from source

bash

git clone https://github.com/justice8096/sagemath-mcp-server.git
cd sagemath-mcp-server
npm install
npm run build
npm start

Configuring an MCP client

Claude Desktop / Claude Code (stdio transport)

Add to ~/.claude.json (or the equivalent Claude Desktop config):

json

{
  "mcpServers": {
    "sagemath": {
      "command": "sagemath-mcp"
    }
  }
}

Remote / HTTP transport

bash

TRANSPORT=http API_KEY=your-secret-key npm start

Then point an MCP HTTP client at http://<host>:3000/mcp with the matching API_KEY header.

Architecture

TypeScript wrapper, runtime is Node.js ≥ 18.
Subprocess wrapping — the wrapper code is CC0; SageMath remains GPL-3.0 and runs as a separate process, which is the canonical safe interaction model per the GNU GPL FAQ on aggregation. Embedding via FFI would propagate copyleft; subprocess execution does not.
Dual transport — stdio (Claude Desktop, Claude Code, local MCP clients) and Streamable HTTP (remote deployment, optional API_KEY env var).
i18n — English, Spanish, French via src/i18n.ts and locales/.
Multi-format build — build.ts emits Claude plugin, OpenAI function-calling, n8n node, MCP server descriptor, CLI tool, and YAML prompt-library outputs from the same source manifest.

Configuration

Env var	Default	Purpose
`TRANSPORT`	`stdio`	`stdio` or `http`.
`PORT`	`3000`	HTTP port when `TRANSPORT=http`.
`API_KEY`	(none)	If set, HTTP requests must include matching `API_KEY` header.
`SAGE_TIMEOUT`	`30000`	Per-call SageMath timeout in milliseconds.
`SAGE_DOCKER_IMAGE`	`sagemath/sagemath:latest`	Image used when SageMath isn't installed locally.

Security

All SageMath input is sanitized to strip shell metacharacters before subprocess execution; see src/services/sage-executor.ts.
HTTP transport requires API_KEY if set — there is no default credential.
See SECURITY.md and THREAT_MODEL.md for the full posture.
Pre-commit audit suite under audits/: SAST/DAST scan, supply-chain audit, CWE mapping, LLM-compliance report, contribution analysis.

License

This wrapper is released under CC0-1.0 (public domain). SageMath itself remains GPL-3.0; the subprocess execution model keeps the licenses independent. See SECURITY.md and the project's compliance analysis for the legal reasoning.

Status

v1.0.0 — public release. The wrapper layer is stable; the SageMath surface is feature-rich and stable upstream. File issues at https://github.com/justice8096/sagemath-mcp-server/issues.

Install

Configuration

Environment variables

SAGE_TIMEOUT

Per-call SageMath timeout in milliseconds. Default 30000.

SAGE_DOCKER_IMAGE

Docker image used when SageMath is not installed locally. Default sagemath/sagemath:latest.

TRANSPORT

Transport mode: 'stdio' (default) or 'http'.

PORT

HTTP port when TRANSPORT=http. Default 3000.

API_KEYsecret

If set, HTTP transport requires matching API_KEY header. Ignored for stdio.

claude_desktop_config.json

{
  "mcpServers": {
    "sagemath-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@justice8096/sagemath-mcp-server@1.0.1"
      ],
      "env": {
        "SAGE_TIMEOUT": "<YOUR_SAGE_TIMEOUT>",
        "SAGE_DOCKER_IMAGE": "<YOUR_SAGE_DOCKER_IMAGE>",
        "TRANSPORT": "<YOUR_TRANSPORT>",
        "PORT": "<YOUR_PORT>",
        "API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}