AI导哈

快速Bash命令执行服务器

一个高性能的MCP服务器，为Claude Code提供快速的Bash命令执行功能，绕过基于haiku的预检检查，减少30秒以上的延迟。

  • by NikkeTryHard
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 NikkeTryHard/fast-bash-mcp

使用说明

克劳德代码的快速Bash MCP服务器

一个高性能的MCP服务器，为Claude Code提供快速的bash命令执行，绕过了导致30秒以上延迟的基于俳句的慢速飞行前检查。

问题

Claude Code内置的Bash工具 每个命令有两个LLM API调用:

  1. bash_extract_prefix -执行前的飞行前检查
  2. bash_extract_command_paths -执行后文件路径提取

这些调用经过配置的俳句模型，可以添加 30+秒的延迟 每个bash命令，即使是简单的操作，如 git status 或 ls.

调查结果

因素 影响 状态
Shell配置文件启动 95ms 不是问题
代理延迟 1-2s 不是问题
Bubblewrap沙盒 最小 不是问题
命令注入检查 最小 不是问题
Haiku LLM来电 30+秒 根本原因

GitHub相关问题

  • #10181 -壳体轮廓干扰
  • #3505 -2分钟超时问题
  • #19585 -Shell快照创建超时
  • #4049 -飞行前Haiku模型访问被拒绝
  • #19247 -基本工具调用挂起

解决方案

此MCP服务器提供无需LLM飞行前检查的直接bash执行，为您提供Claude Code的速度 ! 前缀，但代理可以通过编程访问。

特性

工具 说明
fast_bash 具有所有选项的单一命令执行
fast_bash_parallel 使用摘要同时运行多个命令
fast_bash_sequence 在单个shell会话中按顺序运行命令

fast_bash参数

参数 类型 默认值 说明
command string 必需 要执行的bash命令
cwd string 项目目录 工作目录
timeout number 420000 超时（毫秒）（最大600000）
description string - 日志记录的简短描述
shell string bash 外壳：bash、zsh或sh
env object - 其他环境变量
stdin string - 输入管道到命令
max_output number 30000 截断限制（字符）
output_file string - 将完整的stdout保存到文件
stderr_file string - 将完整的stderr保存到文件
login_shell boolean true 以登录shell（-l标志）运行到源配置文件

fast_bash_paralle参数

参数 类型 默认值 说明
commands array required 命令对象数组（请参阅fast_bash）
default_cwd string 项目目录 所有命令的默认工作目录
default_timeout number 420000 所有命令的默认超时时间（毫秒）
output_file string - 将组合输出保存到文件

fast_bash_sequence参数

参数 类型 默认值 说明
commands array required ｛command，description？｝对象数组
stop_on_failure boolean true 命令失败时停止执行
continue_on_codes number[] [0] 退出代码被视为成功
cwd string 项目 初始工作目录
timeout number 420000 所有命令的总超时时间（毫秒）
shell string bash 外壳：bash、zsh或sh
env object - 其他环境变量
output_file string - 将完整输出保存到文件

v3.2功能

  • 7分钟默认超时：所有工具默认为420秒（7分钟），每次请求最多可覆盖10分钟
  • 安全强化 （可通过以下方式切换 FAST_BASH_HARDENED):
    • 路径遍历和系统目录写保护 output_file/stderr_file
    • 环境变量注入过滤(LD_PRELOAD, DYLD_INSERT_LIBRARIES等等）
    • max_output 天花板（10MB）
  • OOM保护：stdout/stderr累积的内存上限为50MB（始终处于活动状态）
  • Sudo拒绝：命令包含 sudo 被一条询问人类的消息屏蔽
  • 默认登录shell：来源 .bashrc/.profile 因此，PATH和别名是可用的
  • 顺序执行: fast_bash_sequence 在单个shell会话中运行命令，其中 cd 和 export 在命令之间保持不变
  • 指数化产出：并行命令显示 [N] 前缀为故障摘要
  • 错误分类：退货 error_type （超时、已杀死、spawn_error、command_not_found、permission_desided、cwd_not_found）
  • CWD验证：工作目录不存在时清除错误消息
  • 优雅的超时：SIGTERM优先，5秒宽限期后SIGKILL
  • 输出文件重定向：在截断之前保存完整输出 output_file/stderr_file
  • 中间截断：保留大量产出的开始和结束

快速安装

使用Claude CLI（推荐）

# Clone the repo
git clone https://github.com/nikketryhard/fast-bash-mcp.git ~/.claude/mcp-servers/fast-bash

# Install dependencies
cd ~/.claude/mcp-servers/fast-bash && bun install

# Add MCP server using Claude CLI
claude mcp add --transport stdio -e FAST_BASH_DEFAULT_CWD='${PWD}' fast-bash -- bun run ~/.claude/mcp-servers/fast-bash/src/index.ts

# Restart Claude Code

作用域选项

# User scope (default) - available in all projects
claude mcp add fast-bash -- bun run ~/.claude/mcp-servers/fast-bash/src/index.ts

# Project scope - only in current project (.claude/settings.local.json)
claude mcp add --scope project fast-bash -- bun run ~/.claude/mcp-servers/fast-bash/src/index.ts

# Local scope - gitignored, only your machine (.claude/settings.local.json)
claude mcp add --scope local fast-bash -- bun run ~/.claude/mcp-servers/fast-bash/src/index.ts

手动安装

# Clone the repo
git clone https://github.com/nikketryhard/fast-bash-mcp.git ~/.claude/mcp-servers/fast-bash

# Install dependencies
cd ~/.claude/mcp-servers/fast-bash && bun install

# Restart Claude Code

然后添加到 ~/.claude.json:

{
  "mcpServers": {
    "fast-bash": {
      "command": "bun",
      "args": ["run", "/home/YOUR_USERNAME/.claude/mcp-servers/fast-bash/src/index.ts"],
      "env": {
        "FAST_BASH_DEFAULT_CWD": "${PWD}"
      }
    }
  }
}

配置

环境变量

变量 默认值 描述
FAST_BASH_DEFAULT_CWD process.cwd（） 默认工作目录
FAST_BASH_HARDENED off 设置为 1 实现安全强化（见下文）

安全强化

默认情况下，强化模式为 关。要启用它，请设置 FAST_BASH_HARDENED=1 在MCP配置中：

{
  "mcpServers": {
    "fast-bash": {
      "command": "bun",
      "args": ["run", "/path/to/fast-bash-mcp/src/index.ts"],
      "env": {
        "FAST_BASH_DEFAULT_CWD": "${PWD}",
        "FAST_BASH_HARDENED": "1"
      }
    }
  }
}

启用硬化模式时：

保护 说明
路径净化 output_file/stderr_file 无法使用 .. 或写信至 /etc/, /usr/, /bin/, /sbin/, /boot/, /dev/, /proc/, /sys/
Env-var滤波 积木 LD_PRELOAD, LD_LIBRARY_PATH, DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH 从 env 参数
输出上限 max_output 上限为10MB

始终处于活动状态 （无论硬化模式如何）：

  • Sudo拒绝 --命令包含 sudo 被封锁
  • OOM保护 --stdout/stderr累积的内存上限为50MB
  • 超时上限 --每个命令最多10分钟（600000ms）

MCP服务器配置（~/.claude.json）

添加 mcpServers 到你的 ~/.claude.json:

{
  "mcpServers": {
    "fast-bash": {
      "command": "bun",
      "args": ["run", "/path/to/fast-bash-mcp/src/index.ts"],
      "env": {
        "FAST_BASH_DEFAULT_CWD": "${PWD}"
      }
    }
  }
}

禁用内置Bash（可选）

增添 ~/.claude/settings.json:

{
  "permissions": {
    "deny": ["Bash"]
  }
}

指导Claude使用Fast Bash

增添 ~/.claude/CLAUDE.md:

BASH COMMANDS 0. ALWAYS use fast-bash MCP tools instead of the built-in Bash tool.

1. Use mcp**fast-bash**fast_bash for single commands
2. Use mcp**fast-bash**fast_bash_parallel for multiple independent commands
3. Use mcp**fast-bash**fast_bash_sequence for sequential commands where cd/export persist
4. Commands run from project directory by default. Pass cwd parameter to override.

使用示例

单一命令

{
  "command": "git status",
  "description": "Check git status"
}

带输出文件的单个命令

{
  "command": "npm test",
  "output_file": "/tmp/test-output.txt",
  "stderr_file": "/tmp/test-errors.txt"
}

并行命令

{
  "commands": [
    { "command": "git status", "description": "Git status" },
    { "command": "npm test", "description": "Run tests" },
    { "command": "npm run build", "description": "Build project" }
  ],
  "default_cwd": "/path/to/project"
}

输出包括索引结果和摘要：

[1] === Git status ===
$ git status
...
[exit code: 0]
[52ms]

[2] === Run tests ===
...

=== Summary ===
Total: 1523ms | Succeeded: 2 | Failed: 1
Failed: [3]
Longest: [2] Run tests (1200ms)

顺序命令（有状态）

{
  "commands": [
    { "command": "cd /tmp", "description": "Change dir" },
    { "command": "export FOO=bar", "description": "Set env" },
    { "command": "echo $FOO && pwd", "description": "Verify" }
  ],
  "stop_on_failure": true,
  "continue_on_codes": [0]
}

与平行不同， cd 和 export 在命令之间持续。

运作原理

Claude Code的Bash工具

Command -> Haiku LLM (prefix extraction) -> Execute -> Haiku LLM (path extraction) -> Result
           ~15-30 seconds                              ~15-30 seconds

快速Bash MCP

Command -> Execute -> Result
           ~50ms

MCP服务器使用Node.js child_process.spawn 直接绕过所有基于LLM的检查。

工作目录行为

  • 命令从以下位置运行 项目目录 默认情况下（Claude Code启动的地方）
  • ${PWD} 在Claude Code启动时被捕获，并通过env var传递
  • 对于 fast_bash 和 fast_bash_parallel: cd 做 不坚持 通话之间
  • 对于 fast_bash_sequence: cd 持续 序列内（单个shell会话）
  • 使用 cd dir && command 或传递显式 cwd 参数

与内置Bash的比较

特性 内置Bash 快速Bash MCP
速度 30+秒 ~50ms
飞行前LLM检查 是 否
飞行后LLM检查 是 否
沙盒 是（气泡膜） 否
cwd持久性 是 是（仅序列）
输出截断 是（30k） 是（可配置）
并行命令 否 是
顺序命令 否 是
错误分类 否 是
输出文件重定向 否 是
优雅超时 否 是（SIGTERM+SIGKILL）
默认超时 10分钟 7分钟
OOM保护 否 是（50MB上限）
安全强化 基于沙盒 可切换（环境变量）

需求

  • 包子 运行时
  • 克劳德代码2.0+

许可证

麻省理工学院

贡献

PR欢迎！请先打开一个问题来讨论更改。

相关 MCP