MCP Sandbox

MCP サンドボックス

mcp sandbox をぜひお試しください

中文文档 | 英語

デモ

Python MCP Sandbox は、ユーザーや LLM が隔離された Docker コンテナ内で Python コードを安全に実行し、パッケージをインストールできる、対話型の Python コード実行ツールです。

Viby

Viby は mcp sandbox と連携します

特長

• 🐳 Docker による隔離：隔離された Docker コンテナ内で Python コードを安全に実行します
• 📦 パッケージ管理：カスタム PyPI ミラーに対応し、Python パッケージを簡単にインストール、管理できます
• 📊 ファイル生成：ファイルを生成し、ウェブリンクからアクセスできます
• 🔐 認証：複数ユーザー環境向けに、API キーベースの認証を任意で設定できます
• 🎨 ウェブ UI：サンドボックスの管理や実行結果の確認に使えるウェブインターフェースを内蔵しています
• 🌐 SSE 対応：MCP 統合向けに、Server-Sent Events によるリアルタイム通信に対応しています

インストール

# Clone the repository
git clone https://github.com/JohanLi233/python-mcp-sandbox.git
cd python-mcp-sandbox

# Install dependencies using uv
uv venv
uv sync

# Start the server
uv run main.py

デフォルトの SSE エンドポイントは http://127.0.0.1:8181/sse です。MCP Inspector から SSE 経由で、または SSE 接続に対応した他のクライアントから接続できます。

設定

サーバーの設定は config.toml でカスタマイズできます。

• ホスト：デフォルトは 127.0.0.1（localhost のみ）
• ポート：デフォルトは 8181
• PyPI ミラー：使用する Python パッケージインデックスのミラーを設定します

外部からのアクセスを許可するには、設定ファイルでホストを 0.0.0.0 に変更してください。

使用可能なツール

1. create_sandbox：新しい Python Docker サンドボックスを作成し、以降のコード実行やパッケージインストールに使用する ID を返します
2. list_sandboxes：再利用できる既存のサンドボックス（Docker コンテナ）をすべて一覧表示します
3. execute_python_code：指定した Docker サンドボックス内で Python コードを実行します
4. install_package_in_sandbox：指定した Docker サンドボックス内に Python パッケージをインストールします
5. check_package_installation_status：Docker サンドボックス内で、パッケージがインストールされているか、またはインストール状況を確認します
6. execute_terminal_command：指定した Docker サンドボックス内でターミナルコマンドを実行します。パラメーター：sandbox_id（文字列）、command（文字列）。stdout、stderr、exit_code を返します。
7. upload_file_to_sandbox：ローカルファイルを指定した Docker サンドボックスにアップロードします。パラメーター：sandbox_id（文字列）、local_file_path（文字列）、dest_path（文字列、省略可能、デフォルト：/app/results）。

プロジェクト構成

python-mcp-sandbox/
├── main.py                    # Application entry point
├── requirements.txt           # Project dependencies
├── Dockerfile                 # Docker configuration for Python containers
├── results/                   # Directory for generated files
├── mcp_sandbox/               # Main package directory
│   ├── __init__.py
│   ├── models.py              # Pydantic models
│   ├── api/                   # API related components
│   │   ├── __init__.py
│   │   └── routes.py          # API route definitions
│   ├── core/                  # Core functionality
│   │   ├── __init__.py
│   │   ├── docker_manager.py  # Docker container management
│   │   └── mcp_tools.py       # MCP tools
│   └── utils/                 # Utilities
│       ├── __init__.py
│       ├── config.py          # Configuration constants
│       ├── file_manager.py    # File management
│       └── task_manager.py    # Periodic task management
└── README.md                  # Project documentation

プロンプトの例

I've configured a Python code execution sandbox for you. You can run Python code using the following steps:

1. First, use the "list_sandboxes" tool to view all existing sandboxes (Docker containers).
   - You can reuse an existing sandbox_id if a sandbox exists, do not create a new one.
   - If you need a new sandbox, use the "create_sandbox" tool.
   - Each sandbox is an isolated Python environment, and the sandbox_id is required for all subsequent operations.

2. If you need to install packages, use the "install_package_in_sandbox" tool
   - Parameters: sandbox_id and package_name (e.g., numpy, pandas)
   - This starts asynchronous installation and returns immediately with status

3. After installing packages, you can check their installation status using the "check_package_installation_status" tool
   - Parameters: sandbox_id and package_name (name of the package to check)
   - If the package is still installing, you need to check again using this tool

4. Use the "execute_python_code" tool to run your code
   - Parameters: sandbox_id and code (Python code)
   - Returns output, errors and links to any generated files
   - All generated files are stored inside the sandbox, and file_links are direct HTTP links for inline viewing

Example workflow:
- Use list_sandboxes to check for available sandboxes, if no available sandboxes, use create_sandbox to create a new one → Get sandbox_id
- Use install_package_in_sandbox to install necessary packages (like pandas, matplotlib), with the sandbox_id parameter
- Use check_package_installation_status to verify package installation, with the same sandbox_id parameter
- Use execute_python_code to run your code, with the sandbox_id parameter

Code execution happens in a secure sandbox. Generated files (images, CSVs, etc.) will be provided as direct HTTP links, which can viewed inline in the browser.

Remember not to use plt.show() in your Python code. For visualizations:
- Save figures to files using plt.savefig() instead of plt.show()
- For data, use methods like df.to_csv() or df.to_excel() to save as files
- All saved files will automatically appear as HTTP links in the results, which you can open or embed directly.

MCP 設定例

以下は Claude Desktop の設定例です。

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://127.0.0.1:8181/sse"]
    }
  }
}

認証が有効な場合は、API キーを含めてください。

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://127.0.0.1:8181/sse?api_key=<YOUR_API_KEY>"]
    }
  }
}

オンラインデモ用の MCP 設定例

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://115.190.87.78/sse?api_key=<API_KEY>"]
    }
  }
}

環境に合わせて serverUrl を変更してください。