Sandbox Env MCP

sandbox-mcp

AI エージェントに、永続シェル、ファイルシステム、複数マシンの管理機能を備えた実際の作業環境を提供する MCP サーバーです。Docker コンテナまたはリモート SSH ホストを利用します。

機能

• 永続シェル — ツール呼び出しをまたいで状態が維持される bash または PowerShell のセッションです。環境変数の設定、venv の有効化、ディレクトリの変更が、セッション内に保持されます。
• 複数マシン — 複数の Docker コンテナと SSH ホストを同時に管理できます。それぞれに独立したワークスペースとシェルプールがあります。
• 完全なファイルシステムアクセス — あらゆる対象マシン上のファイルを読み取り、書き込み、パッチ適用、検索できます。すべての書き込みはアトミックです（一時ファイル＋リネーム）。
• 設定不要で起動 — 初回起動時にデフォルトの Docker コンテナを自動作成します。コマンドを1つ実行すれば、すぐに利用できます。
• 段階的なディスカバリー — env ツールで、利用可能な機能を段階的に確認できます。エージェントは env(action="help") を呼び出して、利用できる機能を確認します。
• Docker のライフサイクル管理 — コンテナの作成、停止、起動、再起動、削除ができます。イメージのビルド、設定の確認、状態のコミット、ログの表示も可能です。
• SSH リモートアクセス — SSH 経由で Linux および Windows マシンに接続できます。Windows の対象マシンでは、コードページを自動的に検出します。
• 安全対策 — アクセスをブロックせずに、機密性の高いパス（.ssh、.aws、.env*）について警告します。書き込み前に JSON／YAML／TOML の構文をチェックします。
• 監査記録 — すべてのツール呼び出しを、タイムスタンプ、パラメーター、結果とともに記録します。エージェントのセッション内から検索できます。

クイックスタート

pip install sandbox-env-mcp

# stdio — for Claude Desktop, Cline, Continue
sandbox-mcp

# HTTP — for remote agents
sandbox-mcp-http

初回起動時に、デフォルトのコンテナ（python:3.14-slim、名前は admin）が永続 bash シェルとともに自動的に起動します。ほかに必要な設定はありません。

要件：Python 3.12 以降、Docker SDK、稼働中の Docker デーモンが必要です。SSH モードでは openssh-client が必要です。

ツール

明示的に machine パラメーターを指定しない限り、すべてのツールはデフォルトのマシンを対象にします。

ツール	機能
shell_exec	永続シェルでコマンドを実行します。コマンドの終了まで待機する場合（wait=true、タイムアウトは10秒）と、実行を待たずに返す場合（wait=false）を選べます。
shell_read	実行中または終了したコマンドのバッファーにある出力を読み取ります。
shell_new	マシン上に新しいシェルを作成します。shell_id を返します。
shell_remove	shell_id を指定してシェルを終了し、削除します。
shell_list	状態、マシン、稼働時間、最後のコマンドとともに、すべてのシェルを一覧表示します。
write_stdin	実行中のシェルに生バイトを書き込みます。Ctrl-C（\x03）で割り込みを送るか、read／Read-Host などの対話型プログラムに入力を渡せます。Windows／PowerShell では Ctrl-C はサポートされません（パイプモードにはターミナルドライバーがありません）。代わりにシェルを終了してください。
machine_list	登録済みのすべてのマシンを、バックエンド、状態、用途、シェル数とともに一覧表示します。
default_set	デフォルトのマシン、またはマシンのデフォルトシェルを設定します。
file_read	行番号付きでファイルを読み取ります。オフセットと上限を指定したページ分割に対応しています。
file_write	内容をアトミックに書き込みます。親ディレクトリは自動的に作成されます。
file_patch	あいまい一致による対象を絞った編集を行います。mode=replace（検索して置換）または mode=patch（統合差分）を指定します。
file_search	ファイルの内容を検索（ripgrep）するか、ファイルを検索（glob）します。更新日時順に並べ替えられます。
env	段階的なディスカバリーの入り口です。env(action="help") から始めてください。

監査ログが SQLite データベースの場合は、audit_query が利用できます。エージェントはこのツールで過去のツール呼び出しを検索できます。

シェルの状態

各シェルは、次の4つの状態のいずれかです。

状態	意味	エージェントができること
init	シェルが作成された直後で、起動中です。10 秒後にタイムアウトし、terminated になります。	待機します。準備が整うまで、shell_exec はエラーを返します。
ready	プロンプトが表示され、コマンドを受け付けています。	コマンドを送信し、出力を読み取り、標準入力に書き込めます。
waiting	コマンドが実行中です。	shell_read で出力をポーリングできます。write_stdin で Ctrl-C を送信できます。
terminated	シェルプロセスが終了しました（シグナル、終了コード、タイムアウト、パイプ切断）。最後の出力は保持されています。	残りの出力を読み取った後、shell_remove と shell_new を使って続行します。デフォルトのシェルが自動的に置き換えられることはありません。

主な shell_exec パラメーター：

• wait（デフォルトは true）：コマンドが完了するまで待機します。
• timeout（デフォルトは 10 秒）：期限切れになると、長時間実行されるコマンドでは wait=false と shell_read に切り替えるよう案内し、status="waiting" を返します。
• max_output（デフォルトは 50000 バイト）：返される出力の上限です。超過分は末尾（最後の N バイト）として表示されます。

env アクション

env(action="help") を実行すると、利用可能なアクションが一覧表示されます。env(action="help", topic="<action>") を実行すると、指定したアクションの詳細なドキュメントが返されます。

常に利用可能

アクション	パラメーター	説明
help	topic?	アクションの一覧表示、または1つのアクションのドキュメントを取得します。
status	—	デフォルトのマシン、マシン、シェルを表示します。
list_targets	—	設定から事前定義された SSH ターゲットを表示します。
machine_list	—	登録済みのマシンを表示します。
shell_list	machine?	シェルを表示します。マシンで絞り込むこともできます。
shell_new	machine?、purpose?	新しいシェルセッションを作成します。
shell_remove	shell_id	シェルを終了して削除します。
default_set	machine または shell_id	デフォルトのマシンまたはシェルを設定します。

Docker

アクション	必須パラメーター	説明
docker_run	name、image、purpose	コンテナーを作成して起動します。同名のコンテナーがある場合は再接続します。
docker_ps	—	管理対象のコンテナーを一覧表示します。
docker_images	—	デーモン上のすべてのイメージを一覧表示します。
docker_image_history	image	ビルド履歴をレイヤーごとに表示します。
docker_build	image_tag、machine	/workspace 内の Dockerfile からビルドします。
docker_commit	machine、image_tag	コンテナーを新しいイメージとしてコミットします。
docker_stop	machine	停止します（状態は保持されます）。
docker_start	machine	停止中のコンテナーを起動します。
docker_remove	machine	コンテナーとそのシェルを停止して削除します。
docker_inspect	machine	整理された設定情報を表示します。イメージの場合は kind=image を指定します。
docker_logs	machine	tail、since、until を指定してログを表示します。
docker_diff	machine	イメージとの差分となるファイルシステムの変更を表示します。
docker_stats	machine	CPU／メモリ／ネットワーク／IO のスナップショットを表示します。
docker_restart	machine	停止、起動、検証を行います。

SSH

アクション	必須パラメーター	説明
connect	name	設定済みのターゲットに接続します。
close	name	切断して登録を解除します。

[ssh.targets] が設定されている場合に利用できます。

ファイル操作

ツール	主なパラメーター	特徴
file_read	path、offset、limit	行番号付きで表示します。50 KB を超えるファイルはヒントとともに拒否します。
file_write	path、content	アトミックに書き込み（一時ファイル作成後に名前変更）を行い、親ディレクトリを自動作成して、書き込み後に検証します。
file_patch	path、old_string、new_string（置換モード）または patch（統合 diff）	あいまい一致を行います。BOM と改行コードを保持します。
file_search	pattern、search_type、path、file_glob、limit	ripgrep を使用します。結果は更新日時順に並べ替えられます。

機密性の高いパス（.ssh、.aws、.env*、/etc/shadow など）では、安全性に関する警告が表示されます。警告は助言のみであり、エージェントは引き続き全面的にアクセスできます。.json、.yaml、.yml、.toml への書き込みは、書き込む前に構文チェックされます（チェックに失敗した場合は書き込みを拒否します）。

設定

設定ファイルは ~/.sandbox-mcp/config.toml にあります（ config/config.example.toml をコピーしてください）。すべてのフィールドは SANDBOX_MCP_<SECTION>_<KEY> 環境変数で上書きできます。

[server]
port = 8010
auth_tokens_file = "~/.sandbox-mcp/auth_tokens"

[storage]
work_home = "/var/lib/sandbox-mcp"

[docker]
default_image = "python:3.14-slim"
auto_network = "sandbox-mcp"      # "" = none
admin_machine = "admin"           # "" = no /host mount
host = ""                         # "" = from Docker environment

[ssh]
connect_timeout = 10
[ssh.targets.win-build]
host = "192.168.1.100"
user = "builder"
os_type = "windows"

[default_machine]
enabled = true
backend = "docker"
name = "admin"

[shell]
default_max_output = 50000

[files]
max_file_size = 51200

バックエンド

Docker

コンテナには、ワークスペースを分離するためのバインドマウントが設定されます。

• work_home/<name>/ → /workspace（rw）
• work_home/<share_subdir>/ → /share/（ro、ピア間で共有）
• work_home/<share_subdir>/<name>/ → /share/<name>/（rw オーバーレイ）

コンテナ名が admin_machine と一致する場合は、 work_home/ → /host（rw）も設定され、すべてのワークスペースをまとめて参照できます。

サーバーの起動時に Docker デーモンとの自動照合が行われ、稼働中の コンテナはレジストリに再登録されます。

SSH

接続の再利用には ControlMaster を使用して、SSH 経由で接続します。Windows ターゲットでは、コードページの自動検出とエンコードされたコマンドの実行が行われます。

デプロイ

# docker-compose.yml
services:
  sandbox-mcp:
    image: ghcr.io/hs3434/sandbox-env-mcp:latest
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/sandbox-mcp:/var/lib/sandbox-mcp
      - ./config:/root/.sandbox-mcp

HTTP モードでは、auth_tokens_file からベアラートークンを読み込みます（リクエストごとに再読み込みします）。ファイルが空または存在せず、 auto_generate_if_empty=true の場合、ランダムなトークンが起動時に stderr に出力されます。

監査

すべてのツール呼び出しが記録されます。記録されるのは、タイムスタンプ、マシン、アクション、ステータス、 所要時間、ハッシュ化されたパラメーターです。デフォルトでは SQLite の ~/.sandbox-mcp/audit.db に保存されます。代わりに JSON Lines を stderr に出力するには log_path="" を設定します。