SageMath

SageMath MCP Server

Model Context Protocol サーバーです。SageMath の数学機能からサンドボックス化された一部を LLM に提供します。記号計算、数論、線形代数、常微分方程式、プロット、組合せ論、グラフ、群、楕円曲線などに対応しています。各 MCP セッションには専用の Sage ワーカープロセスが割り当てられるため、変数、関数、仮定はツール呼び出しをまたいで保持されます。40 個の MCP ツールを備えており、その 1 つである verify_claim は、証明の段階を追って提示された結果を再検証し、根拠とともに proved ／ refuted ／ supported ／ undecided のいずれかを返します。

呼び出し元のコードはデフォルトで拒否されます。Sage の数学機能の全範囲を利用できますが、インポート、外部 CAS インターフェース、ファイル／表示／永続化のプリミティブは利用できません。このポリシーは、SageMath 独自のドキュメント化された 438,124 件の doctest 例の**98.9%**を許可します（対象範囲内で拒否されるのは 4,259 件で、すべて名前付きルールに基づいています。passagemath ランタイムでは 433,687 件中 98.9%）。残りは拒否されます。この割合は CI の実行ごとに測定されます（「セキュリティ」を参照）。

マニュアル全文は USAGE.md をご覧ください。ツールとそのパラメーター、コードの解釈方法、セキュリティモデルについて詳しく説明しています。

インストールと実行

推奨 — passagemath Sage ランタイムを使った pip：

pip install "sagemath-mcp[passagemath]"    # ~1 GB, no Docker, no local Sage build
sagemath-mcp                                             # stdio (default)
sagemath-mcp --transport streamable-http --port 8314    # HTTP on 127.0.0.1

または、uv を使い、永続的なインストールを行わない場合は、 uvx --from "sagemath-mcp[passagemath]" sagemath-mcp を実行します。以下で各クライアントにインストールする際も、この方法を使います。

passagemath は、pip でインストールできるモジュール化された SageMath です。from sage.all import * とワーカーは変更せずに動作します。サーバーはインポート時にランタイムを検出し、 対応するセキュリティアーティファクトを読み込むため、デフォルトで拒否するポリシーは どちらの環境でも同等です。バージョンは正確に固定されており（passagemath-standard==10.8.13）、 専用の CI レーンで、固定バージョンに対する全テストスイートと doctest コーパスの一括検証を 実施しています。そのため、固定バージョンの更新はリリース前にエンドツーエンドで検証され、 直近 2 回のリリースはいずれも初回でこの検証を通過しました （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

これらのフラグは、サーバーが想定する強化設定です。サーバーはコードを実行し、 認証を行わないため、ポートは意図的にループバックインターフェイスに公開しています。 docker compose up --build を実行すると、レビュー済みの単一ファイルから同じ強化設定が適用されます。 リリースイメージには Cosign で署名し、レジストリのアテステーションとして SLSA provenance と SPDX SBOM を付与しています。PyPI のファイルには PEP 740 アテステーションが付与されています。 それぞれの検証方法については、DISTRIBUTION.md をご覧ください。

arm64（Apple シリコン、Graviton）の場合：passagemath イメージ。 上記のモノリシックイメージは linux/amd64 のみで公開されているため、arm64 ではエミュレーションで実行されます。 passagemath ランタイムで動作する同じサーバーは、同じ強化フラグ、UID、セキュリティポリシーを備えた ネイティブの linux/amd64 と linux/arm64 のイメージとして提供されています。

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）があり、 各アーキテクチャは公開前にネイティブ環境でスモークテストされます。また、インデックスには プライマリイメージと同様に署名とアテステーションが付与されます。これは amd64 では オプションのイメージであり、モノリシックイメージが引き続きプライマリとなります。

デスクトップ MCP ホスト（Claude Desktop など）でワンクリック： 最新のリリースから sagemath-mcp-<version>.mcpb をダウンロードして開きます。バンドルのサイズは約 27 KB です。 初回起動時に、ホストが uv を使ってサーバーと Sage ランタイムの両方をインストールします。 一度だけ、約 1 GB のダウンロードが必要です。macOS と Linux に対応しています。passagemath の Windows サポートは一部に限られるため、Windows のネイティブ環境には対応していません。 バンドルはご自身の権限で行うローカルインストールです。信頼できない入力を扱う場合や マルチテナント環境で使用する場合は、代わりにコンテナを実行してください。

すでにお持ちの Sage を使う場合（PyPI）：

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

ホスト上で動作する SageMath が必要です。PATH 上に sage があるか、サーバーと同じ環境に 存在する必要があります。コンテナ内の Sage はホスト上のサーバーから利用できません。 ご自身の Sage をお持ちでない場合は、上記の [passagemath] エクストラを使用してください。

conda-forge からインストールする場合（Linux と macOS、conda-forge の Sage と併用）：

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

最低バージョンが重要です。それ以前のリリースでは、conda-forge の sage でワーカーを 起動できません。また、sage が指定されていない場合、ソルバーがそれを選択することがあります。 この sage は 10.9 であり、セキュリティアーティファクトの生成元である 10.10 より 1 リリース 古いため、10.10 で追加された名前は利用できず、許可リストにないものは許可されません。

ソースからのインストール、Docker Compose、Kubernetes Helm チャートについては、 USAGE.md をご覧ください。

MCP クライアントを接続する

どの方法もコマンドひとつ、またはクリックひとつで完了します。以下の各方法では、サーバーとともに Sage ランタイムもインストールされるため、ほかに設定するものはありません。

Claude Desktop — 最新リリースから sagemath-mcp-<version>.mcpb をダウンロードして開きます。クリックひとつで完了し、設定ファイルは不要です。

Claude Code — セッション内で、このリポジトリのマーケットプレイスからプラグインとしてインストールします。

/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

次に、数学の問題を頼んでみましょう。以下の例から始めるとよいでしょう。

知っておくとよい点が3つあります。これらの方法では、PATH に uv が必要です。また、初回の起動時に約1 GBの Sage ホイールがダウンロードされ、以降はキャッシュされます。すでに 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 の条件で解き、その解が ODE を満たすことを確認してください。"
• 一般相対性理論 — "計量 (dx² + dy²)/y² を持つ双曲上半平面で、リッチスカラーを計算し、一定の負の曲率であることを確認してください。"
• 連結した2槽システム — "混合槽2つの線形 ODE 系を解き、それぞれの濃度の長期極限を求めてください。"

各例ではオブジェクトを一度だけ作成し、複数回の呼び出しにわたって調べます。これが 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 リソース（セッションのスナップショット、監視メトリクス、ドキュメントへのリンク）があります。cancel_sage_session よりも interrupt_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() → _sage_worker.py サブプロセスへの JSON リクエスト → 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 では fork（PID）の上限も追加されます。Kubernetes の Pod 仕様には同等の Pod 単位の設定がないため、チャートではチャート側で設定できる項目ではなく、ノードの podPidsLimit が使用されます。

脅威モデルの全容と、ブロック／許可される項目の完全な一覧： SECURITY.md および USAGE.md § Security model。

ドキュメントとその他

• 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 が含まれます。それ以外の場合は、PATH 上の sage または [passagemath] エクストラを使用します）。FastMCP 4.x を基盤としています。

コントリビューション

Issue とプルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。プッシュする前に make lint、make typecheck、make test を実行してください（git config core.hooksPath .githooks でプッシュ前チェックが設定されます）。ロードマップと未対応の作業については、ROADMAP.md をご覧ください。 質問は GitHub Discussions にお寄せください。何を期待できるかは SUPPORT.md に記載されています。

引用

このサーバーを公開済みの研究で使用する場合は、CITATION.cff を使って引用してください。GitHub のサイドバーに「このリポジトリを引用」として表示され、APA 形式と BibTeX 形式で引用できます。数学計算を担う SageMath 自体も引用してください。

ライセンス

MIT — LICENSE をご覧ください。SageMath 自体は GPL-2.0-or-later であり、個別のランタイムとして使用されています。このリポジトリでは SageMath のソースを再配布していません。