Skip to main content

mcp-sage

An MCP server providing persistent SageMath sessions to any MCP-compatible host: Claude Code, Claude Desktop, Cursor, or an agent harness such as mcp-minion.

Without this server, each SageMath computation runs in isolation: loading a list of graphs, analyzing one, then querying its automorphism group would require reloading the graph file three times. The Sage REPL server maintains state across calls, enabling iterative mathematical exploration.

Quickstart

Installed from PyPI (the package is mcp-sage; the unrelated sage-mcp on PyPI is a different project):

uvx mcp-sage

Claude Code / Claude Desktop config (.mcp.json or ~/.claude.json):

{
  "mcpServers": {
    "sage-repl": {
      "command": "uvx",
      "args": ["mcp-sage"]
    }
  }
}

Alternatively, the server is a single file using UV's inline dependency syntax (PEP 723), so a checkout runs without installation:

uv run sage_repl_server.py

An optional --directory /path/to/workdir argument sets the server's working directory, so that relative paths in Sage code (e.g. a file written by the agent) resolve inside a chosen run folder.

Tools

Tool Purpose
sage_start Create a new named session (auto-created on first sage_exec if omitted)
sage_exec Execute Sage/Python code and return results
sage_interrupt Send Ctrl+C to stop long-running computations
sage_stop Terminate a session and release resources
sage_list Show all active sessions

sage_exec returns structured output with separate fields for the expression result, stdout, stderr, and any errors. A configurable timeout (default 60 seconds) prevents hanging on infinite loops.

Architecture

The server drives SageMath through the Jupyter kernel protocol rather than raw subprocess management: reliable prompt detection, clean separation of stdout / stderr / return values, native interrupt support, and robust multi-line input. It injects a KernelSpec directly into the KernelManager, so SageMath's bundled Python runs with ipykernel without touching the user's Jupyter configuration. On session start the server imports sage.all, making all Sage functions immediately available. See SPEC.md for the full tool specification.

Requirements

  • SageMath 10.6+ in PATH (the server launches sage -python)
  • uv

Dependencies (resolved automatically by uv run): mcp (1.x low-level server API; pinned <2), jupyter_client, ipykernel.

Citation

This server was built for and used in the experiments of:

David Seka and Stefan Szeider. Neurosymbolic Discovery of Algebraic Graph Constructions. NeSy 2026 (20th International Conference on Neurosymbolic Learning and Reasoning), PMLR vol. 284. Supplementary archive: https://doi.org/10.5281/zenodo.21850460

License

MIT

Metadata

Release files for mcp-sage 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-sage 0.1.1
File Size Uploaded Provenance Actions
mcp_sage-0.1.1.tar.gz 6.9 kB Without provenance Details for mcp_sage-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-sage 0.1.1
File Interpreter ABI Platform Actions
mcp_sage-0.1.1-py3-none-any.whl Python 3 none any Details for mcp_sage-0.1.1-py3-none-any.whl

Total release size: 14.2 kB

Release files / mcp_sage-0.1.1.tar.gz

Download URL mcp_sage-0.1.1.tar.gz
Size 6.9 kB
Tags Source
SHA-256 checksum
How to use checksums
a34cedb59b12e3ed4f83aa3b22ed467dcbf5a7e6e63f998bfce5de2625c244b3
BLAKE2b-256 checksum
How to use checksums
8319c8ebb582e58e3ba1ae177adba80b123e1113d5c29fda640fdbee5449bc02
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Release files / mcp_sage-0.1.1-py3-none-any.whl

Download URL mcp_sage-0.1.1-py3-none-any.whl
Size 7.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a1737ebf647a272548e48b0b408622f659a49f2b6e7cb63230d0dae6632c15e0
BLAKE2b-256 checksum
How to use checksums
763accb0f8bd54a9264bc768388612fe84811a20ebc885b10455b96f4d2d5c30
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.0

Security for mcp-sage 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page