SageMath MCP

SageMath en entorno aislado para agentes: 40 herramientas para matemáticas exactas y simbólicas con sesión persistente

Documentación

Servidor SageMath MCP

Un servidor de Model Context Protocol que brinda a un LLM un subconjunto matemático aislado de SageMath: cálculo simbólico, teoría de números, álgebra lineal, EDOs, gráficos, combinatoria, grafos, grupos, curvas elípticas y más. Cada sesión MCP obtiene un proceso de trabajo dedicado de Sage, por lo que las variables, funciones y suposiciones persisten entre llamadas a herramientas. Incluye 40 herramientas MCP, una de las cuales — verify_claim — reverifica un resultado declarado mediante una escalera de pruebas y responde proved / refuted / supported / undecided con su evidencia.

El código del llamador está denegado por defecto: se puede acceder a toda la amplitud de las matemáticas de Sage, pero las importaciones, las interfaces CAS externas y las primitivas de archivo / visualización / persistencia no están disponibles. La política acepta el 98.9% de los 438,124 ejemplos de doctest documentados del propio SageMath (4,259 rechazos dentro del alcance, cada uno atribuido a una regla nombrada; 99.0% de 433,289 en el runtime de passagemath) mientras rechaza el resto, medido en cada ejecución de CI (ver Seguridad).

Manual completo: USAGE.md — los parámetros y ejemplos de cada herramienta, cómo se interpreta el código y el modelo de seguridad en profundidad.

Instalación y ejecución

Recomendado — la imagen de contenedor (SageMath incluido):

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

Esas banderas son el endurecimiento que el servidor espera; el puerto se publica en loopback deliberadamente — el servidor ejecuta código y no autentica a nadie. docker compose up --build aplica el mismo endurecimiento desde un archivo revisado. Las imágenes publicadas están firmadas con Cosign y llevan procedencia SLSA y un SBOM SPDX como atestaciones de registro; los archivos de PyPI llevan atestaciones PEP 740. DISTRIBUTION.md muestra cómo verificar cada uno.

Desde PyPI (trae tu propio runtime de Sage):

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

Esto requiere un SageMath funcional en el host — ya sea sage en tu PATH (o en el mismo entorno que el servidor) o la imagen Docker sagemath/sagemath.

Desde conda-forge (Linux y macOS, junto al Sage de conda-forge):

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

El piso de versión importa: las versiones anteriores no pueden iniciar un trabajador en el sage de conda-forge, y sin él el solucionador podría elegir uno. Ese sage es 10.9, una versión detrás del 10.10 del que se generan los artefactos de seguridad, por lo que los nombres que agregó 10.10 no están disponibles y nada fuera de la lista de permitidos se admite.

Un runtime de Sage sin la imagen de 3 GB (passagemath, opcional):

pip install "sagemath-mcp[passagemath]"    # ~1 GB, no Docker, no local Sage build
sagemath-mcp

Un fork modularizado e instalable con pip de SageMath. from sage.all import * y el trabajador se ejecutan sin modificaciones; el servidor detecta el runtime al importar y carga los artefactos de seguridad correspondientes, por lo que la política de denegación por defecto es equivalente en ambos. Está fijado exactamente (passagemath-standard==10.8.12) y se ejercita con su propio carril de CI — la suite completa más el barrido del corpus de doctests contra el pin — por lo que un cambio de pin se verifica de extremo a extremo antes de publicarse (docs/passagemath_evaluation.md). Es el runtime opcional; la imagen monolítica sigue siendo la principal, y para uso no confiable o multiinquilino ejecuta el contenedor independientemente del runtime — una instalación con pip tiene los privilegios de tu usuario, el contenedor agrega aislamiento a nivel de SO.

En arm64 (silicio de Apple, Graviton): la imagen de passagemath. La imagen monolítica anterior se publica solo para linux/amd64, por lo que en arm64 se ejecuta bajo emulación. El mismo servidor en el runtime de passagemath se distribuye como una imagen nativa de linux/amd64 + linux/arm64, con las mismas banderas de endurecimiento, UID y política de seguridad:

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

Cada etiqueta de versión tiene un gemelo -passagemath (vX.Y.Z-passagemath), cada arquitectura se prueba con humo de forma nativa antes de publicarse, y el índice está firmado y atestiguado como la imagen principal. Es la imagen opcional en amd64, donde la monolítica sigue siendo la principal.

Un clic en un host MCP de escritorio (Claude Desktop y similares): descarga sagemath-mcp-<version>.mcpb de la última versión y ábrela. El paquete pesa un par de kilobytes; tu host instala el servidor y un runtime de Sage con uv en el primer lanzamiento, lo que es aproximadamente una descarga de 1 GB una sola vez. macOS y Linux — Windows nativo está excluido porque el soporte de Windows de passagemath es parcial. Un paquete es una instalación local con tus propios privilegios; para uso no confiable o multiinquilino ejecuta el contenedor en su lugar.

Instalación desde fuente, Docker Compose y el gráfico Helm de Kubernetes están en USAGE.md.

Conecta un cliente MCP

Un comando o un clic cada uno. Cada ruta a continuación instala un runtime de Sage junto al servidor, por lo que no hay nada más que configurar.

Claude Desktop — descarga sagemath-mcp-<version>.mcpb de la última versión y ábrela. Un clic, sin archivo de configuración.

Claude Code — como un plugin del marketplace de este repositorio, dentro de una sesión:

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

o como un servidor MCP simple:

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

Gemini CLI — el repositorio es en sí mismo una extensión:

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

Codex CLI

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

Luego pide algunas matemáticas — los ejemplos a continuación son un buen comienzo.

Tres cosas que vale la pena saber. Estas necesitan uv en tu PATH, y el primer lanzamiento descarga aproximadamente 1 GB de ruedas de Sage, que se almacenan en caché después. ¿Ya tienes sage? Elimina [passagemath] de la especificación y usará la tuya. ¿Instalado desde conda-forge? Registra el ejecutable del propio entorno, por ejemplo claude mcp add sagemath -- ~/miniforge3/envs/sage/bin/sagemath-mcp; encuentra el sage a su lado sin que el entorno esté activado. Y una instalación de cualquiera de estos se ejecuta con tus propios privilegios; para uso no confiable o compartido, ejecuta el contenedor y apunta el cliente hacia él.

Fijar una versión, transporte HTTP y la referencia completa del cliente están en USAGE.md.

Pruébalo

Indicaciones que un cliente puede ejecutar una vez que el servidor está conectado:

Oscilador armónico amortiguado — "Resuelve x'' + 2·x' + 5·x = 0 con x(0)=1, x'(0)=0, luego verifica que la solución satisface la EDO."
Relatividad general — "En el semiplano superior hiperbólico con la métrica (dx² + dy²)/y², calcula el escalar de Ricci y confirma que es una curvatura negativa constante."
Sistema acoplado de dos tanques — "Resuelve el sistema de EDOs lineales para dos tanques de mezcla, luego toma el límite a largo plazo de cada concentración."

Cada uno construye un objeto una vez y lo explora a través de llamadas — el caso para evaluate_sage y su sesión persistente.

Las 40 herramientas

Las herramientas matemáticas usan SageMath como backend; los parámetros completos y ejemplos están en USAGE.md.

Categoría	Herramientas
Ejecución principal	`evaluate_sage`, `evaluate_sage_streaming`
Verificación	`verify_claim`
Cálculo	`differentiate_expression`, `integrate_expression`, `limit_expression`, `series_expansion`
Álgebra	`solve_equation`, `simplify_expression`, `expand_expression`, `factor_expression`, `calculate_expression`, `symbolic_sum`
Álgebra lineal	`matrix_multiply`, `matrix_operation`
Ecuaciones diferenciales	`solve_ode`
Teoría de números	`number_theory_operation`
Combinatoria	`combinatorics_operation`
Teoría de grafos / grupos	`graph_operation`, `group_operation`
Curvas elípticas / codificación	`elliptic_curve_operation`, `coding_theory_operation`
Polinomios / booleanos / geometría	`polynomial_ring_operation`, `boolean_algebra_operation`, `geometry_operation`
Estadística / probabilidad	`statistics_summary`, `distribution_operation`
Visualización	`plot_expression`, `plot3d_expression`, `plot_multi_expression`
Métodos numéricos / cálculo vectorial	`find_root`, `vector_calculus_operation`
Control de sesión	`reset_sage_session`, `interrupt_sage_session`, `cancel_sage_session`
Espacios de trabajo nombrados	`start_sage_session`, `list_sage_sessions`, `stop_sage_session`
Diagnósticos	`check_sage_health`, `lookup_sage_doc`

Más los endpoints HTTP /health y /ready y 3 recursos MCP (instantáneas de sesión, métricas de monitoreo, enlaces de documentación). Prefiere interrupt_sage_session sobre cancel_sage_session — detiene un cálculo mientras conserva las variables de la sesión.

Cómo funciona

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

Flujo de solicitud: cliente MCP → una herramienta en tools/ → SageSessionManager.get() → SageSession.evaluate() → solicitud JSON al subproceso _sage_worker.py → validación AST → exec() en el espacio de nombres persistente → respuesta JSON.

Aislamiento de procesos — cada sesión ejecuta Sage en su propio subproceso; un bloqueo o tiempo de espera en uno no puede afectar a otro.
Sesiones con estado — las variables, funciones y suposiciones persisten entre llamadas, lo que permite flujos de trabajo de varios pasos.
Denegación por defecto — un nombre se rechaza a menos que la lista de permitidos generada lo ofrezca o el propio código del llamador lo haya vinculado. Un helper que una futura versión de SageMath agregue se rechaza hasta que alguien lo revise, en lugar de ser accesible el día que llegue.

Seguridad

El validador AST es defensa en profundidad contra accidentes y mal uso casual — no es un límite contra código adversarial determinado. El contenedor es el límite de seguridad. El servidor no tiene autenticación, por lo que cada valor predeterminado es loopback: --host por defecto es 127.0.0.1, el transporte predeterminado es stdio, y Compose / Helm mantienen el endpoint fuera de la red. Pon algo que autentique delante de él antes de exponerlo.

Lo que la política aplica: una lista de permitidos (el código del llamador solo puede leer un nombre que el servidor ofrezca o que el propio llamador haya vinculado); sin importaciones por defecto; eval / exec / compile y la evaluación de cadenas en runtime bloqueadas; acceso dunder bloqueado; las interfaces CAS externas y cada primitiva de archivo / red / persistencia eliminadas del espacio de nombres, por procedencia en lugar de por nombre; y el árbol de paquetes sage cerrado al código del llamador, por lo que un helper se alcanza por su propio nombre o no se alcanza en absoluto. El contenedor agrega una raíz de solo lectura, capacidades eliminadas, no-new-privileges, el perfil seccomp predeterminado y límites de memoria. Compose agrega un límite de bifurcaciones (PID); Kubernetes no tiene un equivalente por pod en la especificación del pod, por lo que en el gráfico eso es el podPidsLimit del nodo en lugar de algo que el gráfico pueda establecer.

Modelo de amenazas completo y las tablas completas de bloqueados / permitidos: SECURITY.md y USAGE.md § Modelo de seguridad.

Documentación y más

USAGE.md — el manual completo: cada herramienta, cómo se interpreta el código, implementación y el modelo de seguridad.
docs/mcp_quickstart.md — un recorrido por la primera sesión.
CHANGELOG.md · ROADMAP.md · CONTRIBUTING.md · SECURITY.md · SUPPORT.md — qué significa "soportado", cadencia de versiones, dónde preguntar. PRIVACY.md — qué conserva el servidor (nada sale de la máquina en la que se ejecuta).

Requisitos

Python 3.12+ y un runtime de SageMath (la imagen del contenedor incluye SageMath 10.10; de lo contrario, sage en PATH, o el extra [passagemath]). Construido sobre FastMCP 4.x.

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas — consulta CONTRIBUTING.md. Ejecuta make lint, make typecheck y make test antes de hacer push (git config core.hooksPath .githooks conecta la verificación previa al push). Hoja de ruta y trabajo abierto: ROADMAP.md. Las preguntas van a GitHub Discussions; SUPPORT.md indica qué esperar.

Cómo citar

Si este servidor forma parte de un trabajo publicado, cítalo mediante CITATION.cff — GitHub lo muestra como Cite this repository en la barra lateral, con APA y BibTeX. Cita también el propio SageMath; es quien hace las matemáticas.

Licencia

MIT — consulta LICENSE. SageMath en sí es GPL-2.0-or-later y se usa como un runtime separado; no se redistribuye ningún código fuente de SageMath en este repositorio.