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.

调查结果

GitHub相关问题

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

解决方案

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

特性

fast_bash参数

fast_bash_paralle参数

fast_bash_sequence参数

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_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"
      }
    }
  }
}

启用硬化模式时：

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

• 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的比较

需求

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

许可证

麻省理工学院

贡献

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