SageMath

SageMath MCP Server

A 个 Model Context Protocol 服务，为 大模型提供一个沙箱化的 SageMath 数学子集 — 符号微积分、数论、线性代数、ODE、绘图、组合数学、图、群、椭圆曲线等。每个 MCP 会话都会分配一个专用的 Sage 工作进程，因此变量、函数和假设会在多次工具调用之间保留。它提供 40 个 MCP 工具，其中一个 — verify_claim — 会通过证明阶梯重新检查 陈述的结果，并根据证据回答 proved / refuted / supported / undecided。

调用方代码采用默认拒绝策略：Sage 数学的全部范围均可使用，但导入、外部 CAS 接口以及文件 / 显示 / 持久化原语不可用。该策略接受 SageMath 自身 438,124 个已记录 doctest 示例中的 98.9% （4,259 个范围内的拒绝案例，每个都归因于一条具名规则；在 passagemath 运行时上则为 433,687 个示例中的 98.9%），同时拒绝其余示例 — 每次 CI 运行都会进行测量（参见安全性）。

完整手册：USAGE.md — 介绍工具及其参数、代码的解释方式，以及深入的安全模型。

安装并运行

推荐方式 — 使用 passagemath Sage 运行时，通过 pip 安装：

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

或者，使用 uv 且无需永久安装任何内容， 运行 uvx --python 3.12 --from "sagemath-mcp[passagemath]" sagemath-mcp。下面每个客户端安装步骤都采用此方式。

此额外依赖请使用 Python 3.12；uvx 命令行会指定此版本，如果机器上没有，uv 会下载。CI 使用 3.12 进行测试，而且这是所有依赖都提供 wheel 的最新版本：在 3.13 及更高版本上，memory-allocator 会从源码编译，因此需要 C 编译器。如果不指定 --python，uv 会选择它自己的最新 Python（撰写本文时为 3.15），安装会因此失败。

passagemath 是可通过 pip 安装的模块化 SageMath。from sage.all import * 和工作进程均无需修改即可运行；服务会在导入时检测运行时并加载相应的安全组件，因此两种运行时上的默认拒绝策略等效。版本已精确锁定（passagemath-standard==10.8.13），并通过专属 CI 流程进行验证 — 对锁定版本运行完整测试套件及 doctest 语料库扫描 — 因此每次发布前都会对版本升级进行端到端验证，最近两个版本均首次通过该关卡 （docs/passagemath_evaluation.md）。 支持 macOS 和 Linux；原生 Windows 支持有限，因此在 Windows 上请使用容器或 WSL。

pip 安装会以你自己的权限运行。 安全策略会拒绝超出数学范围的代码，但它并非操作系统边界（SECURITY.md）。这适合在自己的机器上使用自己的客户端。对于不受信任的输入、共享主机或多租户使用场景，请运行容器。

需要隔离时 — 使用容器镜像（内置 SageMath）：

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

这些标志是服务所要求的加固配置；端口刻意只发布到回环地址 — 服务会执行代码，且不验证任何身份。docker compose up --build 会通过一个经过审核的文件应用相同的加固配置。 发布的镜像使用 Cosign 签名，并附带 SLSA 来源证明和 SPDX SBOM 作为注册表证明；PyPI 文件则附带 PEP 740 证明。 DISTRIBUTION.md 介绍了如何验证这些内容。

在 arm64 上（Apple 芯片、Graviton）：使用 passagemath 镜像。 上述单体镜像仅为 linux/amd64 发布，因此在 arm64 上会通过仿真运行。同一服务在 passagemath 运行时上提供原生 linux/amd64 + linux/arm64 镜像，并采用相同的加固标志、UID 和安全策略：

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

每个发布标签都有一个对应的 -passagemath 标签（vX.Y.Z-passagemath）；每种架构都会在发布前进行原生冒烟测试，索引也会像主镜像一样签名并进行证明。在 amd64 上，它是可选镜像，单体镜像仍是主镜像。

在桌面 MCP 宿主中一键安装（Claude Desktop 等）： 从 最新发布版本下载 sagemath-mcp-<version>.mcpb 并打开。此捆绑包约为 27 KB；宿主会在首次启动时使用 uv 安装服务和 Sage 运行时，需下载约 1 GB，之后只需下载一次。支持 macOS 和 Linux——不支持原生 Windows，因为 passagemath 对 Windows 的支持尚不完整。捆绑包会以你自己的权限在本地安装；若用于不受信任或多租户场景，请改为运行容器。

使用已有的 Sage（PyPI）：

pip install sagemath-mcp
sagemath-mcp                                             # stdio (default)
sagemath-mcp --transport streamable-http --port 8314    # HTTP on 127.0.0.1

这要求主机上有可正常运行的 SageMath：sage 位于你的 PATH 中，或与服务处于同一环境中。容器内的 Sage 无法供主机上的服务使用；如果你没有自己的 Sage，请使用上文的 [passagemath] 额外依赖。

从 conda-forge 安装（Linux 和 macOS，与 conda-forge 的 Sage 并存）：

conda install -c conda-forge "sagemath-mcp>=0.9.4" sage
sagemath-mcp

最低版本要求很重要：较早版本无法在 conda-forge 的 sage 上启动工作进程；如果没有该版本，求解器可能会选择较早版本。该 sage 为 10.9，比生成安全构件所用的 10.10 早一个版本，因此 10.10 新增的名称不可用，且不在允许列表中的任何名称都不会被接受。

源码安装、Docker Compose 和 Kubernetes Helm chart 见 USAGE.md。

连接 MCP 客户端

每种方式都只需一条命令或一次点击。以下所有方式都会在服务旁安装 Sage 运行时，因此无需进行其他设置。

Claude Desktop——从 最新发布版本下载 sagemath-mcp-<version>.mcpb 并打开。一键安装，无需配置文件。

Claude Code——在会话中从此仓库的市场作为插件安装：

/plugin install sagemath-mcp --marketplace XBP-Europe/sagemath-mcp

也可以将其作为普通 MCP 服务使用：

claude mcp add sagemath -- uvx --python 3.12 --from "sagemath-mcp[passagemath]" sagemath-mcp

Gemini CLI——此仓库本身就是一个扩展：

gemini extensions install https://github.com/XBP-Europe/sagemath-mcp

Codex CLI

codex mcp add sagemath -- uvx --python 3.12 --from "sagemath-mcp[passagemath]" sagemath-mcp

然后试着提出一些数学问题——下方的示例是很好的起点。

有三点值得注意。这些方式都需要在你的 PATH 中安装 uv，首次启动时会下载约 1 GB 的 Sage wheel，之后会缓存下来。已经有 sage？从配置中移除 [passagemath]，就会使用你已有的 Sage。如果通过 conda-forge 安装，请注册该环境自己的可执行文件，例如 claude mcp add sagemath -- ~/miniforge3/envs/sage/bin/sagemath-mcp；即使环境未激活，它也会找到旁边的 sage。这些安装都会以你自己的权限运行；若用于不受信任或共享场景，请运行容器并让客户端连接到容器。

固定发布版本、HTTP 传输和完整的客户端参考见 USAGE.md。

试用

连接服务器后，客户端可以运行以下提示词：

• 阻尼谐振子 — “求解 x'' + 2·x' + 5·x = 0，其中 x(0)=1、x'(0)=0，然后验证解满足该 ODE。”
• 广义相对论 — “在度量为 (dx² + dy²)/y² 的双曲上半平面上，计算 Ricci 标量，并确认其曲率为常数负值。”
• 耦合双水箱系统 — “求解两个混合水箱的线性 ODE 系统，然后求各自浓度的长期极限。”

每个示例都会构建一次对象，并在多次调用中对其进行探索——这正是使用 evaluate_sage 和持久化会话的理由。

40 个工具

数学工具使用 SageMath 作为后端；最常用工具的参数和示例见 USAGE.md。

类别	工具
核心执行	evaluate_sage、evaluate_sage_streaming
验证	verify_claim
微积分	differentiate_expression、integrate_expression、limit_expression、series_expansion
代数	solve_equation、simplify_expression、expand_expression、factor_expression、calculate_expression、symbolic_sum
线性代数	matrix_multiply、matrix_operation
微分方程	solve_ode
数论	number_theory_operation
组合数学	combinatorics_operation
图论 / 群论	graph_operation、group_operation
椭圆曲线 / 编码理论	elliptic_curve_operation、coding_theory_operation
多项式 / 布尔代数 / 几何	polynomial_ring_operation、boolean_algebra_operation、geometry_operation
统计 / 概率	statistics_summary、distribution_operation
可视化	plot_expression、plot3d_expression、plot_multi_expression
数值方法 / 向量微积分	find_root、vector_calculus_operation
会话控制	reset_sage_session、interrupt_sage_session、cancel_sage_session
命名工作区	start_sage_session、list_sage_sessions、stop_sage_session
诊断	check_sage_health、lookup_sage_doc

此外还有 HTTP /health 和 /ready 端点，以及 3 个 MCP 资源（会话快照、监控指标、文档链接）。建议优先使用 interrupt_sage_session，而非 cancel_sage_session——它会停止计算，同时保留会话中的变量。

工作原理

┌─────────────────────────────────────────────────────────────┐
│  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)         │
└─────────────────────────────────────────────────────────────┘

请求流程： MCP 客户端 → tools/ 中的工具 → SageSessionManager.get() → SageSession.evaluate() → 向 _sage_worker.py 子进程发送 JSON 请求 → AST 验证 → 在持久化命名空间中执行 exec() → 返回 JSON 响应。

• 进程隔离 — 每个会话都在自己的子进程中运行 Sage；一个会话崩溃或超时不会影响其他会话。
• 有状态会话 — 变量、函数和假设会在多次调用之间保留，从而支持多步工作流。
• 默认拒绝 — 除非某个名称在生成的允许列表中，或由调用方自己的代码绑定，否则都会被拒绝。未来 SageMath 新增的辅助函数在经过审核之前都会被拒绝，不会在新增后立即开放访问。

安全

AST 验证器是**针对意外情况和随意误用的纵深防御——并非抵御蓄意恶意代码的边界。**容器才是安全边界。服务没有身份验证，因此所有默认设置都仅限环回地址：--host 默认为 127.0.0.1，默认传输方式为 stdio，Compose / Helm 会让端点不暴露在网络上。公开之前，请先在它前面部署具备身份验证功能的组件。

策略执行的内容：允许列表（调用方代码只能读取服务提供的名称，或调用方自身绑定的名称）；默认禁止导入；禁止使用 eval / exec / compile 和运行时字符串求值；禁止访问 dunder；按来源而非名称，从命名空间中移除外部 CAS 接口以及所有文件 / 网络 / 持久化原语；并禁止调用方代码访问 sage 包树，因此只能通过自身名称调用辅助函数，否则便无法调用。容器还会采用只读根文件系统、移除能力、no-new-privileges、默认 seccomp 配置文件以及内存上限。Compose 还会设置派生进程（PID）上限；Kubernetes 在 Pod 规范中没有对应的单 Pod 设置，因此 Helm Chart 使用的是节点的 podPidsLimit，而不是由 Chart 设置此项。

完整威胁模型以及完整的拦截 / 允许列表： SECURITY.md 和 USAGE.md § 安全模型。

文档与更多信息

• USAGE.md — 完整手册：介绍每个工具、代码的解释方式、部署和安全模型。
• docs/mcp_quickstart.md — 首次使用指南。
• CHANGELOG.md · ROADMAP.md · CONTRIBUTING.md · SECURITY.md · SUPPORT.md — 说明“受支持”的含义、发布节奏以及提问渠道。PRIVACY.md — 说明服务会保留什么（没有任何数据会离开其运行所在的机器）。

要求

Python 3.12+ 和 SageMath 运行时（容器镜像内置 SageMath 10.10；否则需在 PATH 中提供 sage，或安装 [passagemath] extra）。基于 FastMCP 4.x 构建。

贡献

欢迎提交问题和拉取请求——请参阅 CONTRIBUTING.md。推送前请运行 make lint、make typecheck 和 make test （git config core.hooksPath .githooks 会启用推送前检查）。路线图和待处理工作：ROADMAP.md。 请在 GitHub Discussions 提问； SUPPORT.md 说明了可以期待什么。

引用

如果在已发表的作品中使用了本服务，请通过 CITATION.cff 引用——GitHub 会在侧边栏中将其显示为 引用此仓库，并提供 APA 和 BibTeX 格式。也请引用 SageMath 本身；数学计算由它完成。

许可证

MIT——请参阅 LICENSE。SageMath 本身采用 GPL-2.0-or-later 许可，并作为独立运行时使用；本仓库不会重新分发任何 SageMath 源代码。