MCP Server Sagemath

🚀 MCP SageMath Server

A local SageMath server based on the Model Context Protocol (MCP). Currently, it offers two tools:

• sagemath.version: Query the local SageMath version.
• sagemath.evaluate: Execute SageMath scripts and return standard output/errors.

This project is in the early preview stage (v0.0.1).

✨ Features

• Dual Transport Modes: The default is STDIO, and it can be switched to HTTP via environment variables (supports both GET /mcp and POST /mcp).
• Stateless HTTP Sessions: Avoid errors caused by repeated initializations.
• Reliable Sub - process Wrapper: Return structured errors when SageMath is unavailable without crashing.
• Configurable SageMath Path: Supports source code configuration and environment variable overrides, with a default fallback to the system PATH.

📦 Installation Requirements

• Node.js version 18 or higher (version 20+ is recommended).
• SageMath should be installed locally, and its executable file should be accessible via the command line.

🛠️ Configuring the SageMath Path

The project looks for the SageMath executable file at runtime with the following priority:

1. config.sagePath in src/config.ts (if set to a non - empty string).
2. The environment variable SAGE_PATH.
3. The sage command in the system PATH.

By default, config.sagePath reads the value of the SAGE_PATH environment variable. To set a fixed path, you can explicitly fill it in the file, for example:

export const config = {
  sagePath: "/opt/sage/bin/sage",
};

📦 Installation

• Execute the following command in the root directory of the project:

npm install

💻 Usage Examples

STDIO (Default Mode)

• Build: npm run build
• Run: node dist/index.js
• Test the example client:

  npx -y tsx src/test/stdio-client.ts
  

HTTP Mode (Manually Enabled)

• Start the development server:

  MCP_TRANSPORT=http npm run dev
  

• By default, it listens on http://localhost:3000/mcp. You can adjust the port via the PORT environment variable.
• Quick test:

  MCP_TRANSPORT=http npx -y tsx src/test/client.ts
  

• Endpoint descriptions:
  • GET /mcp: Used for SSE/streaming JSON - RPC.
  • POST /mcp: Standard JSON - RPC over HTTP.

📚 MCP Client Configuration Examples

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" // Optional
      }
    }
  }
}

HTTP

{
  "mcpServers": {
    "sagemath-server-http": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "http",
        "PORT": "3000"
      }
    }
  }
}

🛠️ Provided Tools

sagemath.version

• Output fields: stdout, stderr, exitCode, durationMs, timedOut.
• Suitable for detecting whether SageMath is installed and its version information.

sagemath.evaluate

• Input:
  • code (string) — Required, the SageMath script.
  • timeoutMs (number) — Optional, the timeout period, default is 10000 ms.
• Output is the same as above.
• Execution process: Write the code to a temporary file and then call SageMath to execute it.

🧪 Testing

• STDIO regression test: npx -y tsx src/test/stdio-client.ts
• HTTP regression test: MCP_TRANSPORT=http npx -y tsx src/test/client.ts

⚠️ Important Note

• sagemath.evaluate can run any SageMath code. Please use it only in a trusted environment.
• It is recommended to use containers or sandboxes for further isolation and set resource quotas when necessary.

🗺️ Roadmap

• Expand more SageMath functions (plotting, symbolic computation, etc.).
• Optimize session reuse and resource management for long - running tasks.
• Enhance error classification and rate - limiting strategies.

📄 License

This project is under the MIT License. See LICENSE for details.

🙏 Acknowledgments

• The Model Context Protocol community and SDK.
• The SageMath open - source mathematical system.