SageMath MCP Server

Сервер Model Context Protocol, который предоставляет LLM изолированную математическую среду на базе SageMath. В ней доступны символьные вычисления, теория чисел, линейная алгебра, ОДУ, построение графиков, комбинаторика, теория графов, теория групп, эллиптические кривые и многое другое. Для каждого сеанса MCP запускается отдельный рабочий процесс Sage, поэтому переменные, функции и предположения сохраняются между вызовами инструментов. Сервер включает 40 инструментов MCP. Один из них — verify_claim — проверяет заявленный результат с помощью последовательности методов доказательства и возвращает один из ответов: proved / refuted / supported / undecided, сопровождая его обоснованием.

Код вызывающей стороны работает по принципу запрета по умолчанию: доступен весь спектр математических возможностей Sage, но импорт, внешние интерфейсы CAS, а также средства работы с файлами, отображением и сохранением данных недоступны. Политика разрешает 98.9% из 438,124 документированных примеров doctest самого SageMath: 4,259 примеров, попавших в область действия политики, отклоняются, и каждый такой отказ связан с конкретным правилом. Для среды выполнения passagemath этот показатель составляет 98.9% от 433,687 примеров. Остальные примеры отклоняются. Измерения проводятся при каждом запуске CI (см. раздел Security).

Полное руководство: USAGE.md — описание инструментов и их параметров, принципов интерпретации кода и модели безопасности.

Установка и запуск

Рекомендуемый вариант — pip со средой выполнения Sage на базе passagemath:

pip install "sagemath-mcp[passagemath]"    # ~1 GB, без Docker и локальной сборки Sage
sagemath-mcp                                             # stdio (по умолчанию)
sagemath-mcp --transport streamable-http --port 8314    # HTTP на 127.0.0.1

Также можно воспользоваться uv, не устанавливая пакет постоянно:

uvx --from "sagemath-mcp[passagemath]" sagemath-mcp. Именно этот способ используется во всех приведённых ниже инструкциях по подключению клиентов.

passagemath — это модульный SageMath, который можно установить через pip. from sage.all import * и рабочий процесс запускаются без изменений. При импорте сервер определяет среду выполнения и загружает соответствующие артефакты безопасности, поэтому политика запрета по умолчанию работает одинаково в обоих вариантах. Версия зафиксирована точно (passagemath-standard==10.8.13) и проверяется в отдельном задании CI: весь набор тестов и проверка корпуса doctest выполняются именно с этой версией. Поэтому перед выпуском обновление версии проходит сквозную проверку. Последние два выпуска прошли её с первой попытки (docs/passagemath_evaluation.md).

Поддерживаются macOS и Linux. Поддержка Windows ограничена, поэтому в Windows используйте контейнер или WSL.

При установке через pip сервер работает с вашими правами. Политика безопасности блокирует код, выходящий за пределы математических вычислений, но не обеспечивает изоляцию на уровне операционной системы (SECURITY.md). Такой вариант подходит для собственного клиента на вашем компьютере. Для недоверенного кода, общего хоста или работы с несколькими пользователями запускайте контейнер.

Для изоляции — образ контейнера со встроенным SageMath:

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

Эти флаги обеспечивают предусмотренное для сервера усиление защиты. Порт намеренно опубликован только на loopback: сервер выполняет код и не проводит аутентификацию.

Команда docker compose up --build применяет те же настройки защиты из одного проверенного файла.

Выпускаемые образы подписаны с помощью Cosign и содержат подтверждение происхождения SLSA и SBOM в формате SPDX в виде аттестаций реестра. Файлы PyPI сопровождаются аттестациями PEP 740.

В DISTRIBUTION.md описано, как проверять подписи, происхождение сборок и SBOM.

Для arm64 (Apple silicon, Graviton): используйте образ passagemath. Монолитный образ выше публикуется только для linux/amd64, поэтому на arm64 он запускается с эмуляцией. Тот же сервер на базе среды выполнения passagemath доступен в виде нативных образов для linux/amd64 и linux/arm64 с теми же настройками защиты, UID и политикой безопасности:

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

Для каждого тега выпуска предусмотрен соответствующий тег с суффиксом -passagemath (vX.Y.Z-passagemath). Перед публикацией каждый вариант для отдельной архитектуры проходит нативный smoke-тест. Индекс подписан и заверен аттестациями так же, как основной образ. На amd64 этот образ можно использовать по желанию, но основным остаётся монолитный образ.

Установка в один клик в настольном MCP-клиенте (Claude Desktop и других): скачайте sagemath-mcp-.mcpb из раздела последнего выпуска и откройте файл. Размер пакета — около 27 КБ. При первом запуске клиент установит сервер и среду выполнения Sage с помощью uv; для этого потребуется однократно загрузить около 1 ГБ данных.

Поддерживаются macOS и Linux. Windows не поддерживается, поскольку поддержка Windows в passagemath ограничена. Пакет устанавливается локально и работает с вашими правами. Для недоверенного кода или работы с несколькими пользователями используйте контейнер.

С уже установленным Sage (PyPI):

pip install sagemath-mcp
sagemath-mcp                                             # stdio (по умолчанию)
sagemath-mcp --transport streamable-http --port 8314    # HTTP на 127.0.0.1

На хосте должен быть рабочий SageMath: команда sage должна быть доступна в PATH или в той же среде, что и сервер. Сервер на хосте не сможет получить доступ к Sage, запущенному внутри контейнера. Если у вас нет собственного Sage, используйте дополнительный компонент [passagemath], описанный выше.

Из conda-forge (Linux и macOS, рядом с Sage из conda-forge):

=0.9.4" sage sagemath-mcp">

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

Минимальная версия важна: более ранние выпуски не могут запускать рабочий процесс с sage из conda-forge, а без этого ограничения менеджер зависимостей может выбрать именно его. Этот sage — версии 10.9, на один выпуск старше версии 10.10, на основе которой создаются артефакты безопасности. Поэтому имена, добавленные в 10.10, недоступны, а всё, что отсутствует в списке разрешённых, по-прежнему запрещено.

Установка из исходного кода, Docker Compose и диаграмма Helm для Kubernetes описаны в USAGE.md.

Подключение клиента MCP

Для каждого варианта достаточно одной команды или одного нажатия. Все описанные ниже способы устанавливают среду выполнения Sage вместе с сервером, поэтому дополнительная настройка не требуется.

Claude Desktop — скачайте sagemath-mcp-.mcpb из раздела последнего выпуска и откройте файл. Одно нажатие — файл конфигурации не нужен.

Claude Code — установите плагин из marketplace этого репозитория в рамках сеанса:

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

Или добавьте сервер как обычный сервер MCP:

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

Gemini CLI — сам репозиторий является расширением:

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

Codex CLI

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

Затем предложите решить математическую задачу — для начала подойдут примеры ниже.

Важно учитывать три момента. Для этих способов подключения uv должен быть доступен в PATH. При первом запуске загружается около 1 ГБ Sage wheels; впоследствии они кэшируются. Если у вас уже установлен sage, уберите [passagemath] из спецификации — тогда будет использоваться ваша версия. Если вы установили сервер из conda-forge, укажите исполняемый файл из этой среды, например claude mcp add sagemath -- ~/miniforge3/envs/sage/bin/sagemath-mcp; сервер найдёт расположенный рядом sage, даже если среда не активирована. Любой из этих вариантов установки запускается с вашими правами. Для недоверенного кода или совместного использования запустите контейнер и подключите к нему клиент.

Инструкции по фиксации версии, HTTP-транспорту и полное руководство по подключению клиентов приведены в USAGE.md.

Примеры

Примеры запросов, которые можно отправить клиенту после подключения сервера:

Затухающий гармонический осциллятор — «Реши x'' + 2·x' + 5·x = 0 при условиях

x(0)=1, x'(0)=0, а затем проверь, что решение удовлетворяет ОДУ».

Общая теория относительности — «Для верхней полуплоскости с гиперболической метрикой

(dx² + dy²)/y² вычисли скаляр Риччи и подтверди, что кривизна постоянна и отрицательна».

Связанная система из двух резервуаров — «Реши линейную систему ОДУ для двух смесительных резервуаров, а затем найди предел концентрации в каждом из них при больших временах».

В каждом примере объект создаётся один раз, после чего с ним можно работать в нескольких вызовах. Это наглядно демонстрирует возможности evaluate_sage и постоянного сеанса.

40 инструментов

В качестве вычислительного ядра математические инструменты используют SageMath; параметры и примеры для наиболее востребованных инструментов приведены в USAGE.md.

Категория	Инструменты
Основные вычисления	`evaluate_sage`, `evaluate_sage_streaming`
Проверка	`verify_claim`
Математический анализ	`differentiate_expression`, `integrate_expression`, `limit_expression`, `series_expansion`
Алгебра	`solve_equation`, `simplify_expression`, `expand_expression`, `factor_expression`, `calculate_expression`, `symbolic_sum`
Линейная алгебра	`matrix_multiply`, `matrix_operation`
Дифференциальные уравнения	`solve_ode`
Теория чисел	`number_theory_operation`
Комбинаторика	`combinatorics_operation`
Теория графов и групп	`graph_operation`, `group_operation`
Эллиптические кривые и теория кодирования	`elliptic_curve_operation`, `coding_theory_operation`
Многочлены, булева алгебра и геометрия	`polynomial_ring_operation`, `boolean_algebra_operation`, `geometry_operation`
Статистика и теория вероятностей	`statistics_summary`, `distribution_operation`
Визуализация	`plot_expression`, `plot3d_expression`, `plot_multi_expression`
Численные методы и векторное исчисление	`find_root`, `vector_calculus_operation`
Управление сеансами	`reset_sage_session`, `interrupt_sage_session`, `cancel_sage_session`
Именованные рабочие пространства	`start_sage_session`, `list_sage_sessions`, `stop_sage_session`
Диагностика	`check_sage_health`, `lookup_sage_doc`

Кроме того, доступны конечные точки HTTP /health и /ready, а также 3 ресурса MCP: снимки сеансов, метрики мониторинга и ссылки на документацию. Для остановки вычислений с сохранением переменных сеанса используйте interrupt_sage_session, а не cancel_sage_session.

Принцип работы

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

Обработка запроса: MCP-клиент → инструмент из tools/ →

SageSessionManager.get() → SageSession.evaluate() → JSON-запрос

к подпроцессу _sage_worker.py → проверка AST → exec() в постоянном

пространстве имён → JSON-ответ.

Изоляция процессов — каждый сеанс запускает Sage в отдельном подпроцессе; сбой или превышение времени ожидания в одном сеансе не затрагивают остальные.
Сеансы с сохранением состояния — переменные, функции и допущения сохраняются между вызовами, что позволяет выполнять многошаговые задачи.
Запрет по умолчанию — имя отклоняется, если его нет в сгенерированном списке разрешённых имён и оно не было определено в коде вызывающей стороны. Вспомогательная функция, добавленная в будущую версию SageMath, останется недоступной, пока её не проверят.

Безопасность

Валидатор AST — это дополнительный уровень защиты от случайных ошибок и неосторожного использования, а не барьер против целенаправленного вредоносного кода. Границей безопасности служит контейнер. У сервера нет аутентификации, поэтому все значения по умолчанию ограничивают доступ локальным интерфейсом: для --host задано значение 127.0.0.1, транспортом по умолчанию является stdio, а Compose и Helm не открывают конечную точку для сети. Прежде чем сделать её доступной извне, настройте перед ней компонент с аутентификацией.

Политика безопасности обеспечивает следующее: список разрешённых имён — вызывающий код может читать только имена, предоставленные сервером или определённые самим вызывающим кодом; импорты по умолчанию запрещены; eval / exec / compile и вычисление строк во время выполнения блокируются; доступ к атрибутам dunder запрещён; внешние интерфейсы CAS и все средства работы с файлами, сетью и постоянным хранением удалены из пространства имён на основании происхождения, а не имени; дерево пакета sage закрыто для вызывающего кода, поэтому добраться до вспомогательной функции можно только по её собственному имени — иначе она недоступна. Контейнер также использует корневую файловую систему только для чтения, сбрасывает привилегии, включает no-new-privileges, профиль seccomp по умолчанию и ограничения памяти. Compose ограничивает создание дочерних процессов (PID); в Kubernetes эквивалентной настройки на уровне спецификации пода нет, поэтому в chart за это отвечает параметр узла podPidsLimit, который нельзя задать в самом chart.

Полная модель угроз и таблицы всех заблокированных и разрешённых возможностей приведены в SECURITY.md и USAGE.md § Модель безопасности.

Документация и дополнительная информация

USAGE.md — полное руководство: описание каждого инструмента, правила интерпретации кода, развёртывание и модель безопасности.
docs/mcp_quickstart.md — пошаговое руководство для первого сеанса.
CHANGELOG.md · ROADMAP.md ·

CONTRIBUTING.md · SECURITY.md ·

SUPPORT.md — что означает «поддерживается», как часто выходят релизы и где задать вопрос. PRIVACY.md — какие данные сохраняет сервер (ничего не покидает машину, на которой он работает).

Требования

Python 3.12+ и среда выполнения SageMath (образ контейнера включает SageMath 10.10; в противном случае нужен sage в PATH или дополнительный компонент [passagemath]). Сервер построен на FastMCP 4.x.

Участие в разработке

Будем рады вашим сообщениям об ошибках и pull request — см. CONTRIBUTING.md. Перед отправкой изменений выполните make lint, make typecheck и make test (git config core.hooksPath .githooks включает проверку перед отправкой). План разработки и текущие задачи описаны в ROADMAP.md.

Вопросы можно задать в GitHub Discussions; в SUPPORT.md описано, чего ожидать от поддержки.

Цитирование

Если вы используете этот сервер в опубликованной работе, цитируйте его согласно файлу CITATION.cff. На боковой панели GitHub он отображается как Cite this repository и содержит варианты оформления APA и BibTeX. Также укажите SageMath: именно он выполняет математические вычисления.

Лицензия

MIT — см. LICENSE. SageMath распространяется по лицензии GPL-2.0-or-later и используется как отдельная среда выполнения; исходный код SageMath в этом репозитории не распространяется.