bashterm-mcp

在 VSCode 可见的终端标签页中执行命令的 MCP 服务器，支持完整输出捕获。与内联执行不同，每个命令都在真正的终端中运行，你可以看到、滚动并与之交互。

Windows 兼容版本 — 本 fork 完整支持 Windows 平台，包括中文输出不乱码。

核心功能

• 可见终端：命令在真实的 VSCode 终端标签页中运行，而非隐藏进程。你可以实时查看所有输出。
• 会话复用：run 工具会自动复用空闲会话，仅在需要时创建新终端。
• 长时间运行支持：使用 waitForCompletion: false 实现"发射后不管"模式，随后用 read 逐步获取输出。
• 子代理隔离：通过 agentId 标记会话，将并行代理的工作负载彼此隔离。
• 跨平台：支持 Windows、macOS、Linux。Windows 上中文输出自动解码不乱码。

环境要求

• VS Code 1.93+
• Node.js 20+

快速开始

Claude Code

claude mcp add BashTerm -- npx bashterm-mcp@latest

或使用本 fork 的 Windows 优化版本：

# 下载 .vsix 安装包
# 从 Release 页面下载 bashterm-mcp-0.1.8.vsix
code --install-extension bashterm-mcp-0.1.8.vsix

# 添加 MCP 服务器（使用本地扩展内置的 mcp-entry）
claude mcp add BashTerm -- node "C:\Users\<用户名>\.vscode\extensions\hcdb.bashterm-mcp-0.1.8\dist\mcp-entry.js"

VS Code / Copilot

在 .vscode/mcp.json 中添加：

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

在 .cursor/mcp.json 中添加：

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

在 claude_desktop_config.json 中添加：

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

你的第一个提示

安装完成后，试试问：

在终端中运行 ls -la

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

工具

快速执行

| 工具 | 说明 | |------|------| | run | 一步创建（或复用）终端并执行命令，返回清洁输出和退出码。 |

会话管理

| 工具 | 说明 | |------|------| | create | 创建新的可见终端会话，返回 sessionId。 | | exec | 在已有会话中执行命令并捕获输出。 | | read | 分页读取会话输出，支持增量读取和 tail 模式（offset: -N）。 | | input | 向交互式终端发送文本（用于提示、REPL、确认等）。 | | list | 列出活动会话，可选按 agentId 过滤。 | | close | 关闭终端会话及其 VSCode 标签页。 |

使用模式

简单命令

run 工具处理一切——按需创建终端、执行命令、返回清洁输出：

> 运行 npm test

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

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

长时间运行

对于构建、部署或其他耗时命令：

> 启动 npm run build 不等待，然后检查进度

代理会：

1. 调用 run 设置 waitForCompletion: false —— 立即返回
2. 调用 read 设置 offset: -10 查看最后 10 行
3. 重复直到进程完成

交互式命令

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

> 运行 npm init 并回答提示

代理会：

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

并行代理

子代理可以使用 agentId 在隔离的终端中工作：

> 让一个代理运行测试，另一个运行代码检查

每个子代理获得自己的终端，标记其 agentId，防止输出混淆。

配置

扩展从 VSCode 设置中读取 terminalMcp.* 配置：

| 设置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | terminalMcp.maxSessions | number | 10 | 最大并发终端会话数 | | terminalMcp.commandTimeout | number | 30000 | 默认命令超时（毫秒） | | terminalMcp.maxOutputLines | number | 5000 | 每个会话最大缓冲输出行数 | | terminalMcp.idleTimeout | number | 1800000 | 空闲会话自动关闭时间（毫秒，0=禁用） | | terminalMcp.blockedCommands | string[] | ["rm -rf /"] | 禁止执行的命令列表 |

推荐：设为优先工具

像 Claude Code 这样的 LLM 代理内置了 Bash 工具，会在聊天中内联执行命令。输出嵌入在对话中，难以阅读，尤其是输出冗长的命令。建议告诉代理优先使用本 MCP 工具，而非内置 Bash 工具。

将以下内容添加到项目的 CLAUDE.md（或等效指令文件）中：

## 终端执行

优先使用 BashTerm MCP 工具（`run`、`exec`、`read` 等）来执行命令，而不是使用内置的 Bash 工具。
BashTerm 在可见的 VSCode 终端标签页中运行命令，用户可以实时查看输出。
仅在简单、非交互式操作（如读取环境变量）时回退到内置 Bash 工具。

对于可能超过 30 秒或产生大量输出的命令（构建、测试套件、部署、安装），使用 pull 模式：
1. 调用 `run` 设置 `waitForCompletion: false` 启动命令但不阻塞。
2. 调用 `read` 设置 `offset: -10` 查看最后 10 行输出。
3. 重复步骤 2 直到看到命令完成（查找退出消息、提示或 "Done"）。
4. 向用户报告最终结果。

这样可以防止对话超时，并让用户实时观察终端进度。

为什么重要：

| | 内置 Bash | BashTerm MCP | |---|---|---| | 输出可见性 | 嵌入聊天，难以滚动 | 在 VSCode 终端标签页中可见 | | 实时反馈 | 用户看不到任何输出直到命令完成 | 用户实时观看输出 | | 长时间命令 | 阻塞对话直到超时 | 发射后不管 + 轮询 | | 会话状态 | 每个命令隔离 | 持久化会话，带历史 | | 交互式命令 | 不支持 | 可向提示/REPL 发送输入 |

工作方式

1. VSCode 扩展激活并启动 IPC 服务器（Windows 上使用 Named Pipe，其他平台使用 Unix Socket）
2. MCP 入口（mcp-entry.js）由 MCP 客户端启动，在 JSON-RPC stdio 和 IPC socket 之间建立桥接
3. 命令通过 child_process.exec() 执行，输出直接捕获，不再依赖 Shell Integration API
4. 输出存储在循环缓冲区中，支持分页高效读取

最新更新 (0.1.8)

• 项目改名 bashterm-mcp：全面清理旧名称 vscode-terminal-mcp 引用
• 修复 bin 路径：更正 npm 二进制入口路径
• 动态版本图标：badge 徽章现在反映实际版本号
• 中文 README 补充版本徽章

详见 CHANGELOG.md 查看完整历史。

许可证

MIT