BashTerm MCP

让 AI 生成的 shell 命令在 真实可见的 VSCode 终端里运行。

BashTerm MCP 把 Claude Code 的命令执行变成你能看见、能检查、能中断、能继续交互的过程。不再是隐藏的后台 Bash 调用，而是普通 VSCode 终端标签页：实时输出、历史滚动、交互输入、会话复用和安全控制都在你眼前。

为什么选择 BashTerm MCP

• 默认可见：每条命令都在真实 VSCode 终端标签页中运行，测试、构建、日志和报错都能实时看到。
• 开箱支持 Claude Code：扩展会自动注册 MCP server，并可引导 Claude Code 使用 BashTerm MCP 替代隐藏的内置 Bash。
• 适合长任务：命令可以非阻塞启动，进程持续运行时再增量读取输出。
• 支持交互命令：可以回答提示、驱动 REPL、确认操作，或向同一个终端会话继续发送输入。
• 会话复用：复用已有终端上下文，减少每条命令都新开进程带来的割裂感。
• 并行代理隔离：通过 agentId 让多个 AI worker 使用不同终端，输出清晰不串台。
• 实用安全边界：支持危险命令前缀拦截、工作目录限制、输出缓冲上限和空闲会话自动关闭。
• 可安全回退：可关闭 Claude Code 自动 hook，或一键恢复 Claude Code 默认 Bash 行为。

依赖

| 依赖 | 版本要求 | 检查命令 | 安装方式 | |------|----------|----------|----------| | VSCode | ≥ 1.99 | code --version | code.visualstudio.com | | Node.js | ≥ 20 | node --version | 见下方分平台指引 | | Claude Code | 最新 | claude --version | npm install -g @anthropic-ai/claude-code |

Node.js 安装指引

Windows：

# 方式一：fnm（推荐，支持版本切换）
winget install Schniz.fnm
fnm install 22          # 安装 LTS
fnm use 22
node --version          # 验证

# 方式二：官方安装包
# 访问 https://nodejs.org/ 下载 LTS 安装包，运行安装向导即可。

Linux / macOS：

# 方式一：fnm（推荐）
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22          # 安装 LTS
fnm use 22
node --version          # 验证

# 方式二：nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 22
nvm use 22
node --version          # 验证

# 方式三：系统包管理器（版本可能较旧）
sudo apt install nodejs      # Debian / Ubuntu
sudo dnf install nodejs      # Fedora
brew install node            # macOS Homebrew

Node.js 是必须的：扩展通过 contributes.mcpServers 注册 MCP server 时，会用系统 node 启动 MCP bridge 进程。请确保 node 在 PATH 中可用。

Claude Code 用户：安装扩展后，扩展会自动向 ~/.claude/settings.json 写入 PreToolUse hook，引导 Claude Code 使用 BashTerm MCP 工具。如果使用其它 MCP 客户端，需手动配置 MCP server 连接。

安装

1. 从 VSCode Marketplace 安装 BashTerm MCP。
2. 打开 VSCode。
3. 正常使用 Claude Code。

扩展会通过 contributes.mcpServers 自动注册 MCP server，run、exec、read、input 等工具无需手写 MCP JSON 配置即可使用。

手动安装 MCP 服务器

提示：v0.5.3 起，扩展激活时会自动写入 ~/.claude/mcp.json（用户级）和 ~/.claude.json 中的当前项目条目，通常无需手动配置。以下步骤保留作为备用。

如果 Claude Code 没有自动发现 VSCode 扩展注册的 MCP server，或自动配置未生效，可以按下面的步骤手动配置。

如果还没有安装 Claude Code CLI，先安装并验证：

npm install -g @anthropic-ai/claude-code
claude --version

然后添加 BashTerm MCP：

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

请先安装 BashTerm MCP VSCode 扩展并保持 VSCode 打开。这个命令安装的是 MCP bridge，它会连接到 VSCode 扩展主机注册的本地 socket；如果扩展未运行，就无法创建和控制可见终端。

添加完成后重启 Claude Code，即可看到 BashTerm MCP server。

Claude Code 集成

BashTerm MCP 会向用户级 ~/.claude/settings.json 写入 PreToolUse hook，将复杂 Bash 命令重定向到 BashTerm MCP 工具。同时还会写入 ~/.claude/mcp.json（用户级 MCP 服务配置）和 ~/.claude.json 中的当前项目条目，确保在所有项目中都能自动发现 MCP 服务，无需手动配置。

控制权始终在用户手里：

• 在命令面板执行 BashTerm MCP: Enable Claude Code Hook 可启用 Claude Code hook。
• 关闭 bashterm-mcp-server.autoConfigureClaudeCode 即可停用自动 hook。
• 在命令面板执行 BashTerm MCP: Restore Claude Code Default Bash 可恢复默认 Bash，同时从 ~/.claude/mcp.json 和 ~/.claude.json 中移除 BashTerm MCP 条目。
• 在命令面板执行 BashTerm MCP: Show Diagnostics 可查看当前 socket、discovery registry、Node 路径、workspace 和 MCP bridge 选择结果。

如果你执行了恢复默认 Bash，并希望 VSCode 重启后也保持恢复状态，请同时把 bashterm-mcp-server.autoConfigureClaudeCode 设为 false。

截图

常见使用场景

运行普通命令

告诉 Claude Code：

运行 npm test

BashTerm MCP 会创建或复用一个可见终端，执行命令，并返回清洁输出和退出码。

观察长时间构建

启动 npm run build，不要等待结束，然后持续查看进度

代理可以用 waitForCompletion: false 启动命令，再通过 read 轮询输出；同时你也能在 VSCode 终端里实时观察同一个进程。

处理交互式提示

运行 npm init 并回答提示

代理可以启动进程、读取提示、发送输入，然后一步步驱动交互式命令。

隔离并行代理

让一个代理跑测试，另一个代理跑 lint

每个代理都可以带上自己的 agentId，终端会话和输出流彼此分离。

工具列表

| 工具 | 功能 | |------|------| | run | 创建或复用终端，并一步执行命令。 | | create | 打开可见终端标签页并返回 sessionId。 | | exec | 在已有会话中执行命令并捕获输出。 | | read | 按偏移量分页读取输出，或进入 tail 模式。 | | input | 向交互式进程发送文本。 | | list | 列出活动会话，可按 agentId 过滤。 | | close | 关闭会话及其终端标签页。 |

配置

可在 VSCode 设置中配置 bashterm-mcp-server.*。

| 设置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | bashterm-mcp-server.autoConfigureClaudeCode | boolean | true | 自动配置 Claude Code，使其优先使用 BashTerm MCP 而不是内置 Bash。 | | bashterm-mcp-server.blockedCommands | string[] | ["rm -rf /", "mkfs", "dd if=", ":(){ :|:& };:"] | 始终拒绝执行的命令前缀。 | | bashterm-mcp-server.allowedDirectories | string[] | [] | 允许的工作目录。为空表示不限制。 | | bashterm-mcp-server.defaultTimeoutMs | number | 30000 | 默认命令超时时间，单位毫秒。 | | bashterm-mcp-server.maxConcurrentSessions | number | 10 | 最大并发终端会话数。 | | bashterm-mcp-server.maxOutputLines | number | 10000 | 每个会话最多缓冲的输出行数。 | | bashterm-mcp-server.idleTimeoutMs | number | 300000 | 空闲会话自动关闭时间，单位毫秒。0 表示禁用。 | | bashterm-mcp-server.windowsPreferredPowerShell | string | "powershell" | Windows V2 planner 检测到 PowerShell 语法时使用的 PowerShell 可执行文件。可选值：powershell、pwsh。普通 Windows 命令默认走 cmd。 |

命令面板命令

可在 VSCode 命令面板中执行：

| 命令 | 功能 | |------|------| | BashTerm MCP: Enable Claude Code Hook | 启用 autoConfigureClaudeCode，写入 Claude Code PreToolUse hook，并提示重启 Claude Code。 | | BashTerm MCP: Restore Claude Code Default Bash | 从 ~/.claude/settings.json 中移除 BashTerm MCP hook，同时从 ~/.claude/mcp.json 和 ~/.claude.json 中移除 MCP 服务条目。 | | BashTerm MCP: Show Diagnostics | 打开 BashTerm MCP 输出面板，显示平台、Node、workspace、socket、discovery registry 和 MCP bridge 选择信息。 |

如果需要在命令行排查 MCP bridge，可直接运行：

node /path/to/extension/dist/mcp-entry.js --status

状态输出是 JSON，可以看到 bridge 是否找到了 VSCode 扩展注册的 socket，或者是否因为没有可用 discovery entry 而进入 fallback。

适合什么场景

BashTerm MCP 特别适合那些你希望亲眼观察的命令：测试、包安装、开发服务器、数据库迁移、脚手架工具、部署脚本，以及任何可能需要输入或运行时间较长的命令。

更新日志

完整历史见 CHANGELOG.md。

许可证

MIT