vscode-terminal-mcp

vscode-terminal-mcp

可在可见的 VSCode 终端标签页中执行命令并完整捕获输出的 MCP 服务。与内联执行不同，每条命令都会在真实终端中运行，你可以查看、滚动浏览并与之交互。

主要功能

• 可见终端：命令在真实的 VSCode 终端标签页中运行，而非隐藏进程。你可以实时查看所有内容。
• 会话复用：run 工具会自动复用空闲会话，仅在需要时创建新终端。
• 支持长时间运行的任务：使用 waitForCompletion: false 即可启动后不等待，然后通过 read 增量轮询输出。
• 子 Agent 隔离：使用 agentId 标记会话，以隔离并行 Agent 的工作负载。

要求

• 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

你应该会看到 VSCode 中打开一个新的终端标签页，并显示命令输出。

截图

使用 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

Agent 将：

1. 使用 waitForCompletion: false 调用 run——立即返回
2. 使用 offset: -10 调用 read，检查最后 10 行
3. 重复以上步骤，直到进程完成

交互式命令

适用于需要用户输入的命令：

> Run npm init and answer the prompts

Agent 将：

1. 使用 npm init 调用 run
2. 调用 read 查看提示
3. 调用 input 发送答案

并行 Agent

子 Agent 可以使用 agentId 在相互隔离的终端中工作：

> Have one agent run tests while another runs the linter

每个子 Agent 都会获得一个标记了其 agentId 的独立终端，避免输出混杂。

配置

此扩展会从 VSCode 设置中读取 terminalMcp.* 下的配置：

推荐：设为首选工具

Claude Code 等 LLM Agent 内置了 Bash 工具，可在聊天中直接执行命令。命令输出会嵌入对话中，难以阅读，尤其是输出内容较多的命令。我们建议告知 Agent 优先使用此 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: -20 而不是 offset: -100）可减少捕获的输出量。

工作原理

1. VSCode 扩展激活，并在 Unix 套接字上启动 IPC 服务
2. MCP 入口点（mcp-entry.js）由 MCP 客户端启动，在 JSON-RPC 标准输入/输出与 IPC 套接字之间进行桥接
3. 命令通过 Shell Integration API 在真实的 VSCode 终端中执行，以可靠地捕获输出并检测退出代码
4. 输出存储在循环缓冲区中，并支持分页，以便高效读取

最新更改（0.1.6）

• 添加了用于市场页面的 README 截图
• 所有工具的输出格式更简洁——不再显示原始 JSON
• 修复了 waitForCompletion: false 不起作用的问题
• 禁用了空闲回收器——由用户手动关闭会话
• 每个工作区使用唯一的 IPC 套接字（支持多实例）
• 自定义终端选项卡名称，采用日期格式
• 添加了大量输出处理文档

完整历史记录请参阅 CHANGELOG.md。

许可证

MIT