bash-command-mcp

bash-command-mcp

安全で構造化されたコマンド実行と、第一級のバックグラウンドジョブ管理機能を備えた、高度な Bash MCP サーバーです。

重要なセキュリティ警告

このサーバーは、実行されているマシン上でシェルコマンドを実行します。

bun run index.ts をホスト上で直接実行すると、コマンドはホスト上で、ユーザーの権限で実行されます。 MCP クライアントとプロンプトを完全に信頼できる場合を除き、Docker を使って実行環境を隔離してください。

依存関係をインストールするには：

bun install

stdio 経由で実行するには：

bun run index.ts

Streamable HTTP 経由で実行するには：

BASH_COMMAND_MCP_TRANSPORT=http \
BASH_COMMAND_MCP_HOST=127.0.0.1 \
BASH_COMMAND_MCP_PORT=3000 \
bun run index.ts

npm/npx 経由で実行するには（公開済みパッケージ）：

npx -y bash-command-mcp

このサーバーを選ぶ理由

• 明確な終了コードのセマンティクスを備えた、高精度なシェル実行機能。
• 高度なバックグラウンドプロセスのライフサイクル制御（run_background、wait_background、kill_background）。
• プロセスごとの stdout/stderr ログファイルによる、組み込みの可観測性。
• 本番環境での可視性を高める OpenTelemetry のトレースとメトリクス。
• cwd と env のオーバーライドにより、実行コンテキストを正確に指定できる、エージェントに適した使いやすさ。

ツールの動作

ツール：

• run：コマンドをフォアグラウンドで実行します。 引数：command または cmd、timeoutSeconds（デフォルトは 60、最小値は 1。86400 を超える値はヒントを表示して上限値に制限されます）、省略可能な cwd、省略可能な env。
• run_background：コマンドをバックグラウンドで起動し、stdout/stderr をログファイルに書き込みます。 引数：command または cmd、省略可能な cwd、省略可能な env。
• list_background：ログファイルのパスを含め、追跡中のバックグラウンドプロセスを一覧表示します。
• kill_background：pid で指定した追跡中のバックグラウンドプロセスを停止します。
• tail_background：バックグラウンドプロセスのログから末尾の N 行を表示します。 引数：pid、省略可能な lines（デフォルトは 200、最大値は 5000）。
• wait_background：バックグラウンドプロセスの完了を待ち、最終的なステータスと出力を返します。 引数：pid、省略可能な timeoutSeconds（デフォルトは 60、最小値は 1。86400 を超える値はヒントを表示して上限値に制限されます）。

OpenTelemetry

このサーバーには、トレースとメトリクスのための OpenTelemetry インストルメンテーションが組み込まれています。

• OpenTelemetry パッケージはサーバーパッケージとともにインストールされます。
• OTEL_ENABLED=false に設定されていない限り、テレメトリは初期化されます。
• OTEL_EXPORTER_OTLP_ENDPOINT が設定されている場合、トレースとメトリクスは OTLP HTTP 経由でエクスポートされます。
• OTLP エンドポイントが設定されていない場合は、コンソールエクスポーターが使用されます。

インストルメント対象の操作：

• run、run_background、list_background、tail_background、wait_background、kill_background のツール呼び出しスパン。
• バックグラウンドのライフサイクルスパン／カウンター（started、ended）。
• ツール呼び出し、失敗、タイムアウト、実行時間のヒストグラムに関するメトリクス。

一般的な環境変数：

• OTEL_ENABLED=true|false
• OTEL_SERVICE_NAME=bash-command-mcp
• OTEL_SERVICE_VERSION=1.0.0
• OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
• OTEL_METRIC_EXPORT_INTERVAL_MS=10000
• BASH_COMMAND_MCP_LOG_DIR=/path/to/log-dir

例（localhost 上の OTLP Collector）：

OTEL_ENABLED=true \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_SERVICE_NAME=bash-command-mcp \
npx -y bash-command-mcp

トランスポート

このサーバーは、次の 2 種類のトランスポートをサポートしています。

• stdio：ローカルでプロセスを起動する連携向け。
• http：Streamable HTTP を使用する、リモートまたはネットワーク経由でアクセス可能な MCP クライアント向け。

デフォルトの動作は引き続き stdio であるため、既存のデスクトップ環境や CLI 環境でも引き続き動作します。

HTTP モード用の環境変数：

• BASH_COMMAND_MCP_TRANSPORT=http|stdio
• BASH_COMMAND_MCP_HOST=127.0.0.1
• BASH_COMMAND_MCP_PORT=3000
• BASH_COMMAND_MCP_ALLOWED_HOSTS=localhost,127.0.0.1,[::1]

HTTP モードでは、ループバックアドレスにバインドした場合、デフォルトでホストヘッダーの検証が行われます。0.0.0.0 または :: にバインドする場合は、BASH_COMMAND_MCP_ALLOWED_HOSTS に明示的な許可リストを指定してください。

Docker

イメージをビルドします。

docker build -t bash-command-mcp .

ローカルフォルダーを/workspaceにマウントして実行します。

docker run --rm -i -v "$(pwd):/workspace" bash-command-mcp

Streamable HTTP 経由で実行します。

docker run --rm -p 3000:3000 \
  -e BASH_COMMAND_MCP_TRANSPORT=http \
  -e BASH_COMMAND_MCP_HOST=0.0.0.0 \
  -e BASH_COMMAND_MCP_PORT=3000 \
  bash-command-mcp

/workspaceのマッピングについて：

• 左側（$(pwd)）は、ホストマシン上のフォルダーです。
• 右側（/workspace）は、コンテナー内のパスです。
• この MCP サーバーが実行するコマンドは、/workspace配下のファイルを対象にする必要があります。変更内容は、マッピングされたホスト側のフォルダーに書き戻されます。

Docker で HTTP モードを使用する場合は、0.0.0.0にバインドし、-pでポートを公開してください。コンテナーを localhost の外部に公開する場合は、許可するホスト名をBASH_COMMAND_MCP_ALLOWED_HOSTSに設定してください。

例：

• ホスト上に./project/file.txtがあり、./projectからコンテナーを実行すると、コンテナー内では同じファイルを/workspace/file.txtとして利用できます。