Python Exec Sandbox

mcp-python-exec-sandbox

AI エージェント向けのサンドボックス化された Python 実行環境です。スクリプトはインライン依存関係（PEP 723）を使い、一時的で隔離された環境で実行されます。ホスト環境を汚さず、不要な仮想環境を残さず、パッケージの競合も発生しません。

その理由

どのコーディングエージェントも、すでにホスト上で Python を実行できます。問題はその後です。パッケージが蓄積し、仮想環境が増殖し、予期しない pip install によってシステムが壊れることがあります。mcp-python-exec-sandbox は、こうした問題を解消します。

• スクリプトをサンドボックス内で実行します（Linux では bubblewrap、macOS／その他のプラットフォームでは Docker）
• 依存関係をインラインで宣言し、uv によって一時的に解決します
• ホストの Python、site-packages、仮想環境には一切触れません
• 実行ごとに隔離され、終了後は破棄されます

機能

• サンドボックス化された実行 -- プラットフォーム固有の隔離により、ホストのファイルシステムへのアクセスを防ぎます
• PEP 723 インラインメタデータ -- # /// script ブロックを使って、スクリプト内に依存関係を直接宣言できます
• 複数バージョンの Python -- Python 3.13、3.14、または 3.15 でスクリプトを実行できます（uv が適切なバージョンを自動でダウンロードします）
• 一時的な環境 -- 依存関係は実行ごとに解決され、永続化されません
• パッケージのキャッシュ -- uv のグローバルキャッシュにより、2回目以降のインストールはほぼ瞬時に完了します
• タイムアウトの適用 -- 実行ごとにタイムアウトを設定できます
• 出力の切り詰め -- 想定外の大量出力でエージェントが圧倒されるのを防ぎます

前提条件

すべてのセットアップで必要なもの：

• Python 3.13+ -- MCP サーバーのプロセスを実行するために必要です
• uv -- スクリプトの実行、依存関係の解決、Python バージョンのダウンロードを管理します。また、サーバーをグローバルにインストールせずに実行するための uvx も提供します。

追加の要件は、選択したサンドボックスバックエンドによって異なります。

セットアップ	追加要件	インストール
ネイティブサンドボックス（Linux）	bubblewrap	sudo apt install bubblewrap
Docker サンドボックス（macOS、任意の環境）	Docker Engine	Docker のドキュメントを参照
サンドボックスなし	なし	--

ホストの Python と実行用 Python： これらは独立しています。サーバープロセス自体の実行には Python 3.13+ が必要です。--python-version フラグは、スクリプト の実行に使用する Python のバージョンを指定します。uv が対象のバージョンを自動でダウンロードするため、これらのバージョンでスクリプトを実行するために、ホストに Python 3.14 や 3.15 をインストールする必要はありません。

クイックスタート

Claude Code（Linux -- ネイティブサンドボックス）

claude mcp add python-sandbox -- uvx mcp-python-exec-sandbox

Claude Code（macOS -- Docker サンドボックス、推奨）

claude mcp add python-sandbox -- uvx mcp-python-exec-sandbox

Docker サンドボックスのイメージは、初回使用時に GHCR から自動的に取得されます。手動でのビルドは不要です。

Claude Code（サンドボックスなし）

claude mcp add python-sandbox -- uvx mcp-python-exec-sandbox --sandbox-backend none

Cursor

プロジェクトレベルの .cursor/mcp.json またはグローバルの ~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "python-sandbox": {
      "command": "uvx",
      "args": ["mcp-python-exec-sandbox"]
    }
  }
}

OpenAI Codex CLI

codex mcp add python-sandbox -- uvx mcp-python-exec-sandbox

または、.codex/config.toml に追加します。

[mcp_servers.python-sandbox]
command = "uvx"
args = ["mcp-python-exec-sandbox"]

その他の MCP クライアント

MCP stdio トランスポートをサポートするクライアントであれば、どれでもこのサーバーを利用できます。

{
  "mcpServers": {
    "python-sandbox": {
      "command": "uvx",
      "args": ["mcp-python-exec-sandbox"]
    }
  }
}

複数バージョンの Python

--python-version を使って、特定の Python バージョンを指定します。uv が自動的にダウンロードするため、手動でインストールする必要はありません。

# Python 3.13 (default)
uvx mcp-python-exec-sandbox --python-version 3.13

# Python 3.14
uvx mcp-python-exec-sandbox --python-version 3.14

# Python 3.15
uvx mcp-python-exec-sandbox --python-version 3.15

これはすべてのサンドボックスバックエンドで機能します。Docker サンドボックスでは、コンテナ内の uv が Python のバージョンを管理するため、同じ --python-version フラグを使用できます。

ツール

execute_python

依存関係を自動管理して Python スクリプトを実行します。

パラメーター	型	デフォルト	説明
script	str	必須	PEP 723 のインラインメタデータを含められる Python ソースコード
dependencies	list[str]	[]	マージする追加の PEP 508 依存関係指定子
timeout_seconds	int	30	最大実行時間（1～300）

# Simple script
execute_python(script="print('hello world')")

# Script with dependencies
execute_python(
    script="import requests; print(requests.get('https://httpbin.org/get').status_code)",
    dependencies=["requests"]
)

# Script with inline PEP 723 metadata
execute_python(script="""
# /// script
# dependencies = ["pandas", "matplotlib"]
# ///

import pandas as pd
print(pd.DataFrame({'a': [1,2,3]}).describe())
""")

check_environment

実行環境に関する情報（Python のバージョン、uv のバージョン、プラットフォーム、サンドボックスの状態、設定）を返します。

validate_script

スクリプトを実行せずに、PEP 723 メタデータと依存関係を検証します。

パラメーター	型	デフォルト	説明
script	str	必須	検証する Python ソースコード
dependencies	list[str]	[]	検証する追加の依存関係指定子

サンドボックスバックエンド

バックエンド	プラットフォーム	ツール	備考
native	Linux	bubblewrap	名前空間による分離。ネットワークは許可されます
docker	任意	Docker	コンテナーによる分離、リソース制限
none	任意	--	サンドボックス化なし（推奨されません）

デフォルトのバックエンドは、Linux では native（bubblewrap）、macOS／その他のプラットフォームでは docker です。macOS で --sandbox-backend native を指定すると、自動的に Docker に切り替わります。サンドボックスツールを利用できない場合、サーバーは警告を出して none にフォールバックします。

Docker サンドボックスのセットアップ

Docker サンドボックスイメージは GHCR に公開されており、サーバーの起動時に自動的にプルされます。手動でのセットアップは不要です。

開発用にローカルでビルドするには：

docker build -t ghcr.io/lu-zhengda/mcp-python-exec-sandbox profiles/

CLI オプション

mcp-python-exec-sandbox [OPTIONS]

Options:
  --python-version TEXT     Python version for execution (default: 3.13)
  --sandbox-backend TEXT    native | docker | none (default: native on Linux, docker on macOS)
  --max-timeout INT         Maximum allowed timeout in seconds (default: 300)
  --default-timeout INT     Default timeout in seconds (default: 30)
  --max-output-bytes INT    Maximum output size in bytes (default: 102400)
  --no-warm-cache           Skip cache warming on startup
  --uv-path TEXT            Path to uv binary (default: uv)

開発

セットアップ

git clone https://github.com/lu-zhengda/mcp-python-exec-sandbox.git
cd mcp-python-exec-sandbox
uv sync --dev

プロジェクト構成

src/mcp_python_exec_sandbox/   # Package source
  server.py               # FastMCP server + tool definitions
  executor.py             # uv subprocess orchestration
  script.py               # PEP 723 metadata parsing/merging
  sandbox.py              # Sandbox ABC + factory
  sandbox_linux.py        # bubblewrap sandbox (Linux)
  sandbox_docker.py       # Docker sandbox (macOS/any)
  config.py, cache.py, output.py, errors.py
tests/                    # Unit + integration tests (mocked or local uv)
e2e_tests/                # End-to-end tests (require uv + network)
profiles/                 # Dockerfile, warmup packages
.devcontainer/            # Devcontainer for Linux sandbox testing from macOS

テストの実行

ユニットテストと統合テスト — 高速で、どこでも実行できます：

uv run pytest tests/ -v

E2E テスト — uv とネットワークアクセスが必要です。実際のスクリプト実行、パッケージのインストール、MCP プロトコルのフロー、サンドボックスの適用をテストします：

uv run pytest e2e_tests/ -v

Docker サンドボックスのテスト

Docker E2E テスト（e2e_tests/test_docker_sandbox.py）では、Docker バックエンドを通じた実行、依存関係のインストール、読み取り専用ファイルシステムの適用、ホストからの分離、タイムアウト処理を検証します。

前提条件：

1. Docker がインストールされ、実行中であること
2. サンドボックスイメージをビルドすること：

docker build -t ghcr.io/lu-zhengda/mcp-python-exec-sandbox profiles/

次に、以下を実行します：

uv run pytest e2e_tests/test_docker_sandbox.py -v

Docker を利用できない場合、またはイメージがビルドされていない場合、これらのテストは自動的にスキップされます。

Linux サンドボックスのテスト（devcontainer）

Linux サンドボックステスト（e2e_tests/test_sandbox_enforcement.py::test_linux_sandbox_blocks_etc_shadow）では、名前空間分離に bubblewrap（bwrap）を使用します。bwrap は Linux 専用のため、macOS ではスキップされます。

macOS から実行するには、bwrap がプリインストールされた Ubuntu 24.04 を提供する、同梱の devcontainer を使用します：

VS Code：

1. Dev Containers 拡張機能をインストールします
2. プロジェクトを開き、Reopen in Container を選択します
3. 統合ターミナルで次を実行します：

uv run pytest e2e_tests/test_sandbox_enforcement.py -v

CLI：

# Install the devcontainer CLI (once)
npm install -g @devcontainers/cli

# Build and start the container
devcontainer up --workspace-folder .

# Run the Linux sandbox tests inside the container
devcontainer exec --workspace-folder . uv run pytest e2e_tests/test_sandbox_enforcement.py -v

テストマトリックス

テストスイート	コマンド	要件
ユニットテスト	uv run pytest tests/ -v	uv
統合テスト	uv run pytest tests/test_integration.py -v	uv
E2E（一般）	uv run pytest e2e_tests/ -v	uv、ネットワーク
E2E（Docker サンドボックス）	uv run pytest e2e_tests/test_docker_sandbox.py -v	uv、Docker、サンドボックスイメージ
E2E（Linux／bwrap サンドボックス）	uv run pytest e2e_tests/test_sandbox_enforcement.py -v	uv、bwrap を備えた Linux（または devcontainer）

コントリビューション

• 1つのコミットにつき、論理的な変更は1つにしてください。コミットメッセージは、内容が分かる命令形にしてください。
• コミット前に uv run pytest tests/ -v を実行してください。すべてのテストに合格する必要があります。
• 新機能にはテストを追加してください。ユニットテストは tests/ に、実際の実行が必要な場合は E2E テストを e2e_tests/ に追加してください。
• 依存関係は最小限にしてください。十分な根拠なしに実行時依存関係を追加しないでください。
• server.py のツールドックストリングは、ユーザー向けの MCP ツールの説明です。LLM を対象に記述してください。
• サンドボックスのバックエンドは、問題が発生しても適切に動作を継続できるようにしてください。必要なツール（bwrap、docker）がない場合は、警告を出して NoopSandbox にフォールバックしてください。

ライセンス

MIT