MCP Sidecar

mcp-sidecar

バックグラウンドプロセスを管理する、軽量でクロスプラットフォーム対応の MCP サーバーです。Go で構築されており、ランタイム依存関係なしで単一バイナリとして配布できます。

目的

AI コーディングエージェント（Claude Code、Gemini CLI、Cursor など）には、長時間稼働するプロセスを実行しながら、それらとのやり取りを続ける機能がありません。影響を受ける一般的なワークフローは次のとおりです。

• API サーバーを起動して、準備が整うまで待ち、その後 HTTP リクエストを実行する
• コードの編集を続けながら、ウォッチモードでビルドを実行する
• データベースを起動して、データを投入し、テストを実行してから、停止する

mcp-sidecar は、プロセスのライフサイクル管理を stdio トランスポート経由の MCP ツールとして公開することで、この問題を解決します。

機能

• クロスプラットフォーム -- 単一のコードベースで Windows、Linux、macOS に対応
• 依存関係ゼロ -- 単一の Go バイナリで動作し、ランタイムは不要
• 最小限の機能 -- 不要な複雑さを排した 6 つのツール
• 確実なクリーンアップ -- サーバー終了時にすべての子プロセスを終了します。終了したプロセスは、設定可能な TTL の経過後に自動的に削除されます
• 出力制御 -- リクエストごとの maxBytes とグローバル設定の SIDECAR_MAX_OUTPUT_SIZE で、LLM に返す出力を制限できます
• コマンドのセキュリティ -- 実行可能ファイルの許可リスト、ブロックパターン、監査ログに対応（いずれも任意）

インストール

クイックセットアップ（すべてのエージェント）

サポートされているコーディングエージェントに mcp-sidecar をインストールする最も簡単な方法です。

# Interactive -- detects installed agents and lets you pick
npx add-mcp mcp-sidecar

# Install to a specific agent
npx add-mcp mcp-sidecar -a claude-code
npx add-mcp mcp-sidecar -a cursor
npx add-mcp mcp-sidecar -a vscode

# Install to all detected agents
npx add-mcp mcp-sidecar --all

対応エージェント：Claude Code、Codex、Cursor、VS Code、Gemini CLI、OpenCode、Zed、Goose、Cline など。add-mcp で全リストを確認してください。

手動設定

Claude Code：

claude mcp add sidecar -- npx -y mcp-sidecar

opencode（~/.config/opencode/opencode.json）：

{
  "mcp": {
    "sidecar": {
      "type": "local",
      "command": ["npx", "-y", "mcp-sidecar"],
      "enabled": true
    }
  }
}

汎用（mcp.json）：

{
  "mcpServers": {
    "sidecar": {
      "command": "npx",
      "args": ["-y", "mcp-sidecar"]
    }
  }
}

ソースからのインストール

go install github.com/lsequeiraa/mcp-sidecar@latest

windows/amd64、linux/amd64、darwin/arm64、darwin/amd64 向けのビルド済みバイナリも、GitHub Releases から入手できます。

ツール

ツール	説明	パラメーター	戻り値
start	バックグラウンドプロセスを起動する	command、name?、cwd?、env?	{ id, name, pid }
stop	プロセスを終了する（正常終了後、強制終了）	id	{ id, exitCode, uptime }
list	管理対象の全プロセスを一覧表示する	--	[{ id, name, pid, state, uptime }]
output	バッファーに保存された stdout/stderr を取得する	id、tail?、maxBytes?	{ stdout, stderr, uptime }
send	プロセスの stdin に書き込む	id、input	{ ok }
status	1 つのプロセスの詳細な状態を取得する	id	{ id, name, pid, state, exitCode, uptime, outputSize }

uptime フィールドは実際の稼働時間を表します。実行中のプロセスでは起動してからの時間、終了したプロセスではプロセスが稼働していた時間です（起動してからの経過時間ではありません）。

output ツールの maxBytes パラメーターは、stdout と stderr を合わせた合計バイト数を制限します。tail と maxBytes の両方を指定した場合は、まず tail で行を選択し、その後 maxBytes で結果のバイト数を制限します。出力が上限を超えた場合は、最新の内容を残し、stderr を優先します。切り詰める際は行の境界を維持します。出力が切り詰められた場合、レスポンスには "truncated": true と元のサイズを示す "totalBytes" が含まれます。

プロセスの状態

状態	意味
running	プロセスが実行中です
exited	プロセスが正常に終了しました
failed	ゼロ以外の終了コードでプロセスが終了しました
killed	stop ツールによってプロセスが停止されました

ワークフローの例

エージェントが API サーバーを起動し、準備が整うまで待ってからテストを実行し、最後に停止する一般的なセッションです。

1. start  { command: "dotnet run --project MyApi", name: "api" }
   → { id: "sc-a1b2c3", name: "api", pid: 12345 }

2. output { id: "sc-a1b2c3", tail: 5 }
   → { stdout: "Now listening on: http://localhost:5000", stderr: "", uptime: "3s" }

3. (agent runs curl http://localhost:5000/health using its own shell)

4. output { id: "sc-a1b2c3", tail: 20 }
   → { stdout: "...request logs...", stderr: "", uptime: "15s" }

5. stop   { id: "sc-a1b2c3" }
   → { id: "sc-a1b2c3", exitCode: -1, uptime: "18s" }

エージェントは、短時間で終了するコマンド（curl、ビルドツールなど）にはネイティブのシェルを使用し、複数のツール呼び出しをまたいで稼働させる必要のあるプロセスには mcp-sidecar を使用します。

設定

設定はすべて環境変数で行います（すべて省略可能です）。

変数	デフォルト値	説明
SIDECAR_MAX_PROCESSES	10	同時に実行できるプロセスの最大数
SIDECAR_BUFFER_SIZE	1048576 (1MB)	プロセスごとの出力バッファーサイズ（バイト単位）
SIDECAR_KILL_TIMEOUT	5000	SIGTERM と SIGKILL の間に待機するミリ秒数
SIDECAR_CLEANUP_AFTER	1800 (30 min)	終了したプロセスが自動削除されるまでの秒数。0 = 無効
SIDECAR_MAX_OUTPUT_SIZE	0 (unlimited)	output ツールが返すバイト数の全体上限。0 = 上限なし
SIDECAR_ALLOWED_EXECUTABLES	--	実行可能ファイルの許可リスト（カンマ区切り）（セキュアモードを有効化）
SIDECAR_BLOCKED_PATTERNS	--	コマンドを拒否する正規表現パターン（カンマ区切り）
SIDECAR_AUDIT_LOG	--	監査ログのディレクトリ、または true（カレントディレクトリ）／temp（OS の一時ディレクトリ）

自動クリーンアップに関する注意： SIDECAR_CLEANUP_AFTER が有効な場合（デフォルト）、TTL の期限が切れると終了したプロセスはマネージャーから削除されます。削除後、そのプロセス ID に対する output、status、stop の呼び出しは「not found」を返します。必要な出力は TTL の期間内（デフォルトでは 30 分）に取得してください。

セキュリティ

SIDECAR_ALLOWED_EXECUTABLES が設定されている場合、mcp-sidecar はシェルモードからセキュアモードに切り替わります。

	シェルモード（デフォルト）	セキュアモード
実行方法	sh -c / cmd /C 経由	直接実行（シェルを介さない）
許可リスト	なし	リストに記載された実行可能ファイルのみ実行可能
メタ文字	使用可能（シェルが解釈します）	拒否される（|、&、;、>、<、$、`、(、)）
ブロックパターン	なし	コマンド全体に対して照合する正規表現パターン
監査ログ	なし	すべての開始／停止／ブロックイベントを記録する任意の JSONL ログ

引用符内のメタ文字は使用できます。grep "error|warning" file.txt は、| が二重引用符内にあり、シェルに解釈されないため動作します。

バックスラッシュ（\）は意図的にメタ文字として扱われません。そのため、C:\Users\me\app.exe のような Windows パスをエスケープせずに使用できます。

設定例

Claude Desktop / Cursor（mcp.json）：

{
  "mcpServers": {
    "sidecar": {
      "command": "npx",
      "args": ["-y", "mcp-sidecar"],
      "env": {
        "SIDECAR_ALLOWED_EXECUTABLES": "dotnet,npm,node,git,python",
        "SIDECAR_BLOCKED_PATTERNS": "rm\\s+-rf,--force,--no-verify",
        "SIDECAR_AUDIT_LOG": "./logs"
      }
    }
  }
}

Claude Code：

claude mcp add sidecar \
  -e SIDECAR_ALLOWED_EXECUTABLES=dotnet,npm,node,git,python \
  -e SIDECAR_BLOCKED_PATTERNS="rm\\s+-rf,--force,--no-verify" \
  -e SIDECAR_AUDIT_LOG=true \
  -- npx -y mcp-sidecar

監査ログの形式

監査ログは、設定したディレクトリ内の sidecar-audit.jsonl という名前のファイルに常に書き込まれます。SIDECAR_AUDIT_LOG 変数で保存先を指定します。

値	ログファイルの場所
true	./sidecar-audit.jsonl（カレントディレクトリ）
temp	<OS temp dir>/sidecar-audit.jsonl
./logs	./logs/sidecar-audit.jsonl（ディレクトリは自動作成）

各行は、次の 3 種類のイベントのいずれかを示す JSON オブジェクトです。

{"ts":"2025-03-12T10:00:00Z","event":"start","id":"abc123","command":"dotnet run","cwd":"/app"}
{"ts":"2025-03-12T10:00:05Z","event":"stop","id":"abc123","exit_code":0,"duration":"5s"}
{"ts":"2025-03-12T10:00:06Z","event":"blocked","command":"rm -rf /","reason":"executable \"rm\" is not in allowed list"}

実行可能ファイルの照合

許可リストは、次の 3 種類の照合モードに対応しています。

許可リストの項目	照合対象
dotnet	任意の場所にある dotnet（ベース名で照合）
./build.sh	./build.sh のみ（完全一致）
/usr/bin/python3	/usr/bin/python3 のみ、または PATH 経由で解決される任意の python3

配布

配布経路	使用方法
npm	npx -y mcp-sidecar（@mcp-sidecar/* のオプションパッケージ経由でプラットフォーム用バイナリを使用）
GitHub Releases	各リリースに添付されたビルド済みバイナリ
MCP Registry	io.github.lsequeiraa/mcp-sidecar

ライセンス

MIT