vscode-terminal-mcp

vscode-terminal-mcp

表示されているVS Codeのターミナルタブでコマンドを実行し、出力をすべて取得するMCP サーバーです。インライン実行とは異なり、すべてのコマンドは、表示してスクロールしたり操作したりできる実際のターミナルで実行されます。

主な機能

• 表示されるターミナル：コマンドは隠れたプロセスではなく、実際のVS Codeのターミナルタブで実行されます。すべての様子をリアルタイムで確認できます。
• セッションの再利用：run ツールはアイドル状態のセッションを自動的に再利用し、必要な場合にのみ新しいターミナルを作成します。
• 長時間実行への対応：waitForCompletion: false を指定して実行を開始し、完了を待たずに、read で出力を段階的に確認できます。
• サブエージェントの分離：セッションに agentId を付けて、並列で動作するエージェントの作業を分離できます。

要件

• VS Code 1.93+（Shell Integration API が必要）
• Node.js 20+

はじめに

Claude Code

claude mcp add BashTerm -- npx vscode-terminal-mcp@latest

VS Code / Copilot

.vscode/mcp.json に追加します：

{
  "servers": {
    "BashTerm": {
      "type": "stdio",
      "command": "npx",
      "args": ["vscode-terminal-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "BashTerm": {
      "command": "npx",
      "args": ["-y", "vscode-terminal-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "BashTerm": {
      "command": "npx",
      "args": ["-y", "vscode-terminal-mcp@latest"]
    }
  }
}

最初のプロンプト

インストール後、次のように依頼してみてください：

ターミナルで ls -la を実行してください

コマンドの出力とともに、新しいターミナルタブがVS Codeで開きます。

スクリーンショット

run でコマンドを実行

exec の権限ダイアログ

出力が整ったExecの実行結果

ツール

クイック実行

セッション管理

使用パターン

シンプルなコマンド

run ツールがすべて処理します。必要に応じてターミナルを作成し、コマンドを実行して、整形された出力を返します：

> Run npm test

$ npm test
PASS src/utils.test.ts (3 tests)
PASS src/index.test.ts (5 tests)

[exit: 0 | 1243ms | session-abc123]

長時間実行されるプロセス

ビルド、デプロイ、その他時間のかかるコマンドの場合：

> Start `npm run build` without waiting, then check progress

エージェントは次の操作を行います：

1. waitForCompletion: false を指定して run を呼び出します。すぐに戻ります。
2. offset: -10 を指定して read を呼び出し、末尾10行を確認します。
3. プロセスが完了するまで繰り返します。

対話型コマンド

ユーザー入力が必要なコマンドの場合：

> Run npm init and answer the prompts

エージェントは次の操作を行います：

1. npm init を指定して run を呼び出します。
2. read を呼び出してプロンプトを確認します。
3. input を呼び出して回答を送信します。

並列エージェント

サブエージェントは、agentId を使って分離されたターミナルで作業できます：

> Have one agent run tests while another runs the linter

各サブエージェントには、それぞれの agentId が付けられた専用のターミナルが割り当てられるため、出力が混ざりません。

設定

この拡張機能は、VS Codeの設定にある terminalMcp.* から設定を読み込みます：

推奨：優先ツールとして設定

Claude Code などの LLM エージェントには、チャット内でコマンドを直接実行する組み込みの Bash ツールがあります。出力は会話に埋め込まれるため、特に出力が大量になるコマンドでは読みづらくなります。この MCP を組み込みの Bash ツールより優先して使うよう、エージェントに指示することをおすすめします。

プロジェクトの CLAUDE.md（または同等の指示ファイル）に以下を追加してください。

## Terminal Execution

Prefer the BashTerm MCP tools (`run`, `exec`, `read`, etc.) over the built-in Bash tool for executing commands.
BashTerm runs commands in visible VSCode terminal tabs where the user can see output in real time.
Only fall back to the built-in Bash tool for simple, non-interactive operations like reading environment variables.

For commands that may take longer than 30 seconds or produce large amounts of output (builds, test suites,
deployments, installs), use the pull mode pattern:
1. Call `run` with `waitForCompletion: false` to launch the command without blocking.
2. Call `read` with `offset: -10` to check the last 10 lines of output.
3. Repeat step 2 until you see the command has finished (look for exit messages, prompts, or "Done").
4. Report the final result to the user.

This prevents conversation timeouts and lets the user watch progress in the terminal in real time.

これが重要な理由：

開発：拡張機能の更新

VSCode は拡張機能をメモリに積極的にキャッシュします。ローカルで開発する際、code --install-extension や「Developer: Reload Window」でも、変更が再読み込みされない場合があります。次のワークフローを使用してください。

クイック更新（再起動不要）

ソースファイルを変更したら、ビルドしてインストール済みの拡張機能ディレクトリに直接コピーします。

cd /path/to/vscode-terminal-mcp
npm run build
cp dist/extension.js ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-<version>/dist/extension.js

次に 「Developer: Reload Window」（Ctrl+Shift+P）を実行します。

完全な再インストール（クイック更新で解決しない場合）

VSCode が古いコードを使い続ける場合：

# 1. Uninstall and remove all copies
code --uninstall-extension sirlordt.vscode-terminal-mcp
rm -rf ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-*

# 2. Check for ghost entries with old publisher names
# Look in ~/.vscode/extensions/extensions.json for stale entries
# Remove any entries with old publisher IDs (e.g., "terminal-mcp.vscode-terminal-mcp")

# 3. Close VSCode completely (not just reload)

# 4. Rebuild and install
npm run build
npx vsce package --allow-missing-repository
code --install-extension vscode-terminal-mcp-<version>.vsix --force

# 5. Open VSCode

正しいバージョンが読み込まれていることを確認する

# Check which extension directories exist
ls ~/.vscode/extensions/ | grep terminal

# Verify your changes are in the installed extension
grep "YOUR_UNIQUE_STRING" ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-*/dist/extension.js

# Compare checksums
md5sum dist/extension.js ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-*/dist/extension.js

大きな出力の処理

read の出力が MCP クライアントのトークン上限を超えると、システムは出力全体を一時的な JSON ファイルに自動保存し、エラーメッセージにファイルパスを返します。

必要な内容を取り出すには：

# Get the last 50 lines (most relevant for status)
tail -50 /path/to/saved/file.txt

# Or parse the JSON to extract the text content
python3 -c "import json; data=json.load(open('/path/to/file.txt')); print(data[0]['text'][-2000:])"

ファイル形式は JSON です：[{"type": "text", "text": "..."}]

これは、TUI 出力（プログレスバー、ANSI エスケープコードなど）が大量に生成されるコマンドでよく発生します。取得する出力サイズを減らすには、小さな offset 値（例：offset: -100 ではなく offset: -20）を使用してください。

仕組み

1. VSCode 拡張機能が起動し、Unix ソケット上で IPC サーバーを開始します
2. MCP クライアントによって MCP エントリーポイント（mcp-entry.js）が起動され、JSON-RPC stdio と IPC ソケットを橋渡しします
3. コマンドは、出力の確実な取得と終了コードの検出のために Shell Integration API を使用し、実際の VSCode ターミナルで実行されます
4. 出力は、効率よく読み取れるようページネーションに対応した循環バッファーに保存されます

最新の変更（0.1.6）

• マーケットプレイス向け README のスクリーンショット
• すべてのツールの出力形式を整理 — 生の JSON は表示されなくなりました
• waitForCompletion: false が機能しない問題を修正
• アイドル状態のセッションを終了する機能を無効化 — セッションはユーザーが手動で閉じます
• ワークスペースごとに一意の IPC ソケットを使用（複数インスタンスに対応）
• 日付形式のカスタムターミナルタブ名
• 大きな出力の処理に関するドキュメント

全履歴については、CHANGELOG.md を参照してください。

ライセンス

MIT