Python Code Sandbox MCP

🚀 Python Code Sandbox MCP Server

Pythonサーバーで、一時的なDockerコンテナ内で任意のPythonを実行し、オンザフライでpip依存関係をインストールするためのModel Context Protocol (MCP) を実装しています。

🚀 クイックスタート

このサーバーを使用するには、まずDockerをインストールして実行しておく必要があります。最初の実行時の遅延を避けるために、ベースイメージを事前にプルすることをおすすめします。

docker pull python:3.11-slim

Claude Desktopでの使用方法

claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "python-sandbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-e", "SANDBOX_MEMORY_LIMIT=1g",
        "-e", "SANDBOX_CPU_LIMIT=0.5",
        "aixiaoke/python-code-sandbox-mcp"
      ]
    }
  }
}

手動実行 (Docker)

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e SANDBOX_MEMORY_LIMIT=1g \
  aixiaoke/python-code-sandbox-mcp stdio

ローカル開発 (Dockerパッケージングなし)

ソースコードからサーバーを直接実行する場合（開発またはデバッグ用）は、以下の前提条件を満たす必要があります。

• Python 3.10+
• uv パッケージマネージャー（インストール方法: curl -LsSf https://astral.sh/uv/install.sh | sh または pip install uv）
• Docker（サンドボックスコンテナを実行するために必要）

Windowsユーザーの場合、WSL2バックエンドを使用したDocker Desktopをおすすめします。Docker設定で「Use the WSL 2 based engine」が有効になっていることを確認してください。

手順は以下の通りです。

# 1. リポジトリをクローンする
git clone https://github.com/li-xiu-qi/python-code-sandbox-mcp.git
cd python-code-sandbox-mcp

# 2. 依存関係をインストールする
uv sync --extra dev

# 3. サーバーを実行する
uv run python -m python_code_sandbox_mcp.server

Claude Desktopのローカル開発用の設定は以下の通りです。

{
  "mcpServers": {
    "python-sandbox": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/python-code-sandbox-mcp",
        "python-code-sandbox"
      ]
    }
  }
}

✨ 主な機能

• ファイル永続化 (スマートデフォルト): デフォルトでは、ファイルが自動的にホストファイルシステムに保存されます。
• 分離実行: Pythonコードを一時的なDockerコンテナ（デフォルトでは python:3.11-slim）内で実行します。
• ワンショット実行: 使い捨てのコンテナでスクリプトを実行し、結果を即座に取得します。
• セッションベースの実行: 複雑な多段階タスクのためにコンテナを稼働させ続けます。
• 依存関係管理: PyPIからpipパッケージを自動的にインストールします。
• セキュリティ第一: コンテナ内でCPU/メモリ制限とルート以外のユーザーでの実行を制御します。
• ファイル取得: 自動的に生成された画像（プロット）やファイルをキャプチャします。

📦 インストール

このサーバーを使用するには、Dockerをインストールして実行しておく必要があります。最初の実行時の遅延を避けるために、ベースイメージを事前にプルすることをおすすめします。

docker pull python:3.11-slim

📚 ドキュメント

• 使用ガイド - インストール、設定、および使用方法
• APIリファレンス - 完全なツールドキュメント
• 実行モード - 一時モードとセッションモードの説明
• サンプル - MCPクライアントを使用した実用的なコード例
• 永続化 - ファイルの永続化と保存オプション
• アーキテクチャ - システム設計
• セキュリティ - セキュリティガイドライン
• トラブルシューティング - 一般的な問題と解決策

日本語ドキュメント

• 使用ガイド - インストール、設定、および使用方法の説明
• APIリファレンス - 完全なツールドキュメント
• 実行モード - 一時モードとセッションモードの詳細説明
• 使用例 - 実用的なコード例

🔧 技術詳細

設定

サーバーは環境変数または .env ファイルを使用した設定をサポートしています。主なオプションは以下の通りです。

ファイル永続化 (新機能)

デフォルトでは、サンドボックス内で作成されたファイルはホストファイルシステムに保存されます。

• Windows: %TEMP%/python-sandbox-mcp/files/
• macOS/Linux: /tmp/python-sandbox-mcp/files/

この動作をカスタマイズすることができます。

• SANDBOX_FILES_DIR: ファイルの永続化に使用するカスタムディレクトリを設定します（例: /home/user/my-sandbox-files）
• SANDBOX_FILES_DIR="": 空文字列に設定すると、永続化を無効にします（ファイルはコンテナ内にのみ存在します）

その他のオプション

• PIP_CACHE_PATH: （推奨）ホスト上の永続的なpipキャッシュの絶対パス。
• SANDBOX_MEMORY_LIMIT: コンテナごとの最大メモリ（デフォルト: 2g）。
• SANDBOX_CPU_LIMIT: コンテナごとのCPU制限（デフォルト: 0.5）。
• ENABLE_PIP_CACHE: false に設定すると、キャッシュを無効にします。

すべての変数のリストについては、使用ガイド を参照してください。

ツール

run_python_ephemeral (推奨)

新しい使い捨てコンテナでワンオフのPythonスクリプトを実行します。

入力:

• code (文字列、必須): 実行するPythonソースコード。
• dependencies (文字列の配列、オプション): インストールするpipパッケージ（例: ["pandas", "matplotlib"]）。

動作:

1. 新しいコンテナを作成します。
2. 指定された依存関係をインストールします。
3. スクリプトを実行し、stdout/stderrをキャプチャします。
4. 生成されたファイル（画像は image、その他は resource として）を返します。
5. コンテナを自動的に破棄します。

sandbox_initialize / run_python

永続的なサンドボックスを起動し、同じ環境で複数のスクリプトを実行します。

テストプロンプト

接続後、以下のプロンプトを試して動作を確認してください。

1. Hello World: Create and run a Python script with print("Hello MCP")
2. データ可視化: Install matplotlib and create a sine wave plot saved as 'sine.png'

📄 ライセンス

MIT