Provides tools for executing SageMath scripts and querying version information, enabling mathematical computations and symbolic calculations through the SageMath computer algebra system.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP SageMath Serverwhat's the derivative of x^3 + 2x^2 - 5x + 1?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP SageMath Server
基于 Model Context Protocol (MCP) 的本地 SageMath 服务端，当前提供两项工具：
sagemath_version：查询本地 SageMath 版本。sagemath_evaluate：执行 SageMath 脚本并返回标准输出/错误。sagemath_health：轻量级自检，验证 SageMath 可用性。
项目处于早期预览阶段（v0.0.1）。
功能概览
双传输模式：默认 STDIO，可通过环境变量切换到 HTTP（同时支持
GET /mcp与POST /mcp）。无状态 HTTP 会话：避免重复初始化导致的错误。
可靠的子进程封装：当 SageMath 不可用时返回结构化错误，不会崩溃。
可配置的 SageMath 路径：支持源代码配置与环境变量覆盖，默认回退到系统 PATH。
环境要求
Node.js 18 及以上版本（推荐 20+）。
本地已安装 SageMath，并能够通过命令行访问其可执行文件。
配置 SageMath 路径
项目在运行时按照以下优先级查找 SageMath 可执行文件：
src/config.ts中的config.sagePath（若设置为非空字符串）。环境变量
SAGE_PATH。系统 PATH 中的
sage命令。
默认情况下，config.sagePath 会读取 SAGE_PATH 环境变量的值；如需固定路径，可在该文件内显式填写，例如：
export const config = {
sagePath: "/opt/sage/bin/sage",
};安装
本项目根目录下执行
npm install运行方式
STDIO（默认模式）
构建：
npm run build运行：
node dist/index.js测试示例客户端：
npx -y tsx src/test/stdio-client.ts
HTTP 模式（需手动启用）
启动开发服务器：
MCP_TRANSPORT=http npm run dev默认监听
http://localhost:3000/mcp，可通过PORT环境变量调整端口。开箱测试：
MCP_TRANSPORT=http npx -y tsx src/test/client.ts端点说明：
GET /mcp：用于 SSE/流式 JSON-RPC。POST /mcp：标准 JSON-RPC over HTTP。
MCP 客户端配置示例
STDIO
{
"mcpServers": {
"sagemath-server": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
"autoApprove": ["sagemath_version", "sagemath_evaluate"],
"env": {
// "SAGE_PATH": "/absolute/path/to/sage" // 可选
}
}
}
}HTTP
{
"mcpServers": {
"sagemath-server-http": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
"env": {
"MCP_TRANSPORT": "http",
"PORT": "3000"
}
}
}
}提供的工具
sagemath_version
输出字段：
stdout,stderr,exitCode,durationMs,timedOut。适用于检测 SageMath 是否安装及版本信息。
sagemath_evaluate
输入：
code(string) — 必填，SageMath 脚本。timeoutMs(number) — 可选，超时时间，默认 10000 ms。
输出同上。
执行流程：将代码写入临时文件后调用 SageMath 执行。
sagemath_health
无输入；尝试执行
print(1+1)。输出字段：
ok（布尔）、message（字符串）、details（包含 stdout/stderr/exitCode 等）。用途：Agent 在启动前快速探活。
测试
STDIO 回归测试：
npx -y tsx src/test/stdio-client.tsHTTP 回归测试：
MCP_TRANSPORT=http npx -y tsx src/test/client.ts
面向 Agent 的兼容性提示（Claude / Trae / 其他 MCP 客户端）
统一结构化输出：所有工具均返回
structuredContent（JSON 对象），并附带简短文本提示；不再需要从content[0].text手动 JSON 解析。推荐探活流程：HTTP/STDIO 连接后先调用
sagemath_health确认 SageMath 可用，再调用其他工具。HTTP 端点：默认
http://localhost:3000/mcp（可改PORT）。支持GET /mcp（SSE/流式 JSON-RPC）与POST /mcp。STDIO：直接执行
node dist/index.js（或开发模式npx -y tsx src/index.ts）。安全提示：
sagemath_evaluate可执行任意 Sage 代码；HTTP 模式建议放在受控网络或加鉴权/限流。
配置示例（可折叠）
~/.config/modelcontext/mcp.json 里增加：
{
"mcpServers": {
"sagemath-server": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
"autoApprove": ["sagemath_version", "sagemath_evaluate", "sagemath_health"],
"env": {
// "SAGE_PATH": "/absolute/path/to/sage"
}
}
}
}希望走 HTTP 时，可改用：
{
"mcpServers": {
"sagemath-server-http": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
"env": {
"MCP_TRANSPORT": "http",
"PORT": "3000"
},
"client": {
"url": "http://localhost:3000/mcp"
}
}
}
}若希望 Claude 直接以 STDIO 启动：
{
"mcpServers": {
"sagemath-server": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
"autoApprove": ["sagemath_version", "sagemath_evaluate", "sagemath_health"],
"env": {
// "SAGE_PATH": "/absolute/path/to/sage"
}
}
}
}Claude Desktop/MCP 配置中添加：
{
"mcpServers": {
"sagemath-server-http": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
"env": {
"MCP_TRANSPORT": "http",
"PORT": "3000"
},
"client": {
"url": "http://localhost:3000/mcp"
}
}
}
}{
"mcpServers": {
"sagemath-server-dev": {
"command": "npx",
"args": [
"-y",
"tsx",
"/Users/halois/workdir/Toolkit/mcps/mcp-server-sagemath/src/index.ts"
],
"autoApprove": ["sagemath_version", "sagemath_evaluate", "sagemath_health"],
"env": {
// "SAGE_PATH": "/absolute/path/to/sage"
}
}
}
}{
"mcpServers": {
"sagemath-server-http": {
"command": "node",
"args": ["/Users/halois/workdir/Toolkit/mcps/mcp-server-sagemath/dist/index.js"],
"env": {
"MCP_TRANSPORT": "http",
"PORT": "3000"
// "SAGE_PATH": "/absolute/path/to/sage"
},
"client": {
"url": "http://localhost:3000/mcp"
},
"autoApprove": ["sagemath_version", "sagemath_evaluate", "sagemath_health"]
}
}
}安全提示
sagemath_evaluate可运行任意 SageMath 代码，请仅在可信环境使用。建议在需要时结合容器或沙箱进一步隔离，并设置资源配额。
Roadmap
扩展更多 SageMath 功能（绘图、符号计算等）。
优化长时间任务的会话复用与资源管理。
增强错误分类与限流策略。
许可证
MIT License，详见 LICENSE。
鸣谢
Model Context Protocol 社区及 SDK。
SageMath 开源数学系统。
更新日志
0.0.2（未发布）：增加
sagemath_health自检工具；统一工具返回的structuredContent，客户端无需手动解析content；README 增补 Codex/Claude STDIO/HTTP 配置示例。0.0.1：初始版本，提供
sagemath_version与sagemath_evaluate。