sagemath-mcp-server

SageMath MCP 服务

一个 Model Context Protocol 服务，可将 SageMath——一个包含 100 多个软件包的计算机代数系统——提供给 Claude 等大模型客户端。大多数“数学 MCP”都只封装单个库（SymPy、mathjs），而本项目通过子进程封装整个 SageMath 技术栈，让模型能够使用真正的符号数学，而非仅仅进行算术运算。

原因

大模型不擅长精确算术，处理多步代数运算时容易出错，在符号运算至关重要时也不可靠。合适的做法是让模型进行概念性推理，并将机械性计算交给工具——就像有计算障碍的人使用计算器一样。SageMath 为这种委派提供了最广泛的工具：因式分解、积分、特征值、数论、LaTeX 渲染和绘图，都可通过一个接口使用。

工具

工具	描述
sage_evaluate	运行任意 SageMath 表达式。
sage_solve_equation	对代数方程／超越方程进行符号求解。
sage_differentiate	计算导数（任意阶数、任意变量）。
sage_integrate	计算不定积分和定积分。
sage_simplify	化简表达式（default、full、trig、rational）。
sage_factor	对多项式或整数进行因式分解。
sage_matrix_ops	在 QQ／RR／ZZ／CC 上计算行列式、逆矩阵、特征值、秩、RREF 和转置。
sage_plot	绘制表达式并返回 base64 PNG。
sage_latex_convert	将 SageMath 表达式转换为 LaTeX。
sage_number_theory	is_prime、next_prime、factor、euler_phi、gcd、lcm、prime_range、sigma、moebius。

所有工具都遵循相同的架构模式（参见 src/schemas/common.ts）。

安装

服务需要主机上安装本地 SageMath 或 Docker，以便启动 SageMath 进程。

选项 1：npm + 本地 SageMath

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

选项 2：Docker（无需本地安装 SageMath）

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

选项 3：从源代码安装

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

配置 MCP 客户端

Claude Desktop / Claude Code（stdio 传输）

将以下内容添加到 ~/.claude.json（或对应的 Claude Desktop 配置文件）：

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

远程／HTTP 传输

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

然后将 MCP HTTP 客户端指向 http://<host>:3000/mcp，并设置匹配的 API_KEY 请求头。

架构

• TypeScript 封装层，运行时为 Node.js ≥ 18。
• 子进程封装——封装代码采用 CC0 许可；SageMath 仍采用 GPL-3.0 许可，并作为独立进程运行，这是根据 GNU GPL 常见问题中关于聚合的说明所述的规范安全交互模式。通过 FFI 嵌入会传递著作权左派要求；通过子进程执行则不会。
• 双传输方式——stdio（Claude Desktop、Claude Code、本地 MCP 客户端）和 Streamable HTTP（远程部署，可选 API_KEY 环境变量）。
• 国际化——通过 src/i18n.ts 和 locales/ 提供英语、西班牙语和法语。
• 多格式构建——build.ts 根据同一份源清单生成 Claude 插件、OpenAI 函数调用、n8n 节点、MCP 服务描述文件、命令行工具和 YAML 提示词库输出。

配置

环境变量	默认值	用途
TRANSPORT	stdio	stdio 或 http。
PORT	3000	当 TRANSPORT=http 时使用的 HTTP 端口。
API_KEY	（无）	设置后，HTTP 请求必须包含匹配的 API_KEY 请求头。
SAGE_TIMEOUT	30000	每次调用的 SageMath 超时时间，单位为毫秒。
SAGE_DOCKER_IMAGE	sagemath/sagemath:latest	本地未安装 SageMath 时使用的镜像。

安全性

• 所有 SageMath 输入都会在子进程执行前进行清理，以移除 Shell 元字符；详见 src/services/sage-executor.ts。
• 如果设置了 API_KEY，HTTP 传输就必须使用该密钥；没有默认凭据。
• 完整的安全状况请参阅 SECURITY.md 和 THREAT_MODEL.md。
• audits/ 下的提交前审计套件：SAST/DAST 扫描、供应链审计、CWE 映射、LLM 合规报告、贡献分析。

许可证

此封装以 CC0-1.0（公有领域）发布。SageMath 本身仍采用 GPL-3.0；子进程执行模式使两者的许可证保持独立。法律依据请参阅 SECURITY.md 和项目的合规性分析。

状态

v1.0.0 — 正式公开发布。封装层已稳定；SageMath 的功能丰富且上游版本稳定。请通过 https://github.com/justice8096/sagemath-mcp-server/issues 提交问题。