AI导哈

Bash命令MCP服务器

一个高度复杂的Bash MCP服务器，用于安全、结构化的命令执行和后台作业编排。

  • by mrorigo
  • TypeScript
  • 混合部署
  • 2 星标
  • 更新于
在 GitHub 查看 mrorigo/bash-command-mcp

使用说明

bash命令mcp

一个高度复杂的Bash MCP服务器，用于安全、结构化的命令执行，并具有一流的后台作业编排。

重要安全警告

此服务器在运行它的计算机上执行shell命令。

如果你跑 bun run index.ts 命令直接在您的主机上运行，并具有您的用户权限。 除非您完全信任MCP客户端和提示，否则请使用Docker隔离执行。

要安装依赖项，请执行以下操作：

bun install

要运行stdio，请执行以下操作：

bun run index.ts

要在Streamable HTTP上运行：

BASH_COMMAND_MCP_TRANSPORT=http \
BASH_COMMAND_MCP_HOST=127.0.0.1 \
BASH_COMMAND_MCP_PORT=3000 \
bun run index.ts

要通过npm/npx（已发布的包）运行：

npx -y bash-command-mcp

为什么选择此服务器

  • 高保真shell执行，具有清晰的退出代码语义。
  • 高级后台流程生命周期控制(run_background, wait_background, kill_background).
  • 通过每个进程的stdout/stderr日志文件内置可观察性。
  • OpenTetry跟踪和生产可见性指标。
  • 易于代理的人体工程学 cwd 和 env 用于精确执行上下文的重写。

工具行为

工具：

  • run：在前台运行命令。 Args： command 或 cmd, timeoutSeconds （默认值 60，min 1；以上值 86400 带有提示），可选 cwd，可选 env.
  • run_background：在后台启动命令，并将stdout/stderr写入日志文件。 Args： command 或 cmd，可选 cwd，可选 env.
  • list_background：列出跟踪的后台进程，包括日志文件路径。
  • kill_background：通过以下方式停止跟踪后台进程 pid.
  • tail_background：显示后台进程日志的最后N行。 Args： pid，可选 lines （默认值 200，最大值 5000).
  • wait_background：等待后台进程完成并返回最终状态/输出。 Args： pid，可选 timeoutSeconds （默认值 60，min 1；以上值 86400 以提示结尾）。

开放遥测

此服务器包括用于跟踪和度量的内置OpenTetry仪器。

  • OpenTetry软件包与服务器软件包一起安装。
  • 遥测初始化，除非 OTEL_ENABLED=false.
  • 如果 OTEL_EXPORTER_OTLP_ENDPOINT 设置后，跟踪/指标通过OTLP HTTP导出。
  • 如果没有配置OTLP端点，则使用控制台导出器。

仪表化操作：

  • 工具调用跨度 run, run_background, list_background, tail_background, wait_background，以及 kill_background.
  • 后台生命周期跨度/计数器(started, ended).
  • 工具调用、故障、超时和持续时间直方图的指标。

常见环境变量：

  • OTEL_ENABLED=true|false
  • OTEL_SERVICE_NAME=bash-command-mcp
  • OTEL_SERVICE_VERSION=1.0.0
  • OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
  • OTEL_METRIC_EXPORT_INTERVAL_MS=10000
  • BASH_COMMAND_MCP_LOG_DIR=/path/to/log-dir

示例（本地主机上的OTLP收集器）：

OTEL_ENABLED=true \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_SERVICE_NAME=bash-command-mcp \
npx -y bash-command-mcp

运输

此服务器支持两种传输方式：

  • stdio 对于本地、流程衍生的集成。
  • http 用于使用Streamable HTTP的远程或网络可访问的MCP客户端。

默认行为保持不变 stdio 因此现有的桌面和CLI设置可以继续工作。

HTTP模式的环境变量：

  • BASH_COMMAND_MCP_TRANSPORT=http|stdio
  • BASH_COMMAND_MCP_HOST=127.0.0.1
  • BASH_COMMAND_MCP_PORT=3000
  • BASH_COMMAND_MCP_ALLOWED_HOSTS=localhost,127.0.0.1,[::1]

HTTP模式在绑定到环回地址时默认使用主机标头验证。如果你绑定到 0.0.0.0 或 ::，在中提供明确的允许列表 BASH_COMMAND_MCP_ALLOWED_HOSTS.

码头工人

塑造形象：

docker build -t bash-command-mcp .

在装载了本地文件夹的情况下运行 /workspace:

docker run --rm -i -v "$(pwd):/workspace" bash-command-mcp

通过流式HTTP运行：

docker run --rm -p 3000:3000 \
  -e BASH_COMMAND_MCP_TRANSPORT=http \
  -e BASH_COMMAND_MCP_HOST=0.0.0.0 \
  -e BASH_COMMAND_MCP_PORT=3000 \
  bash-command-mcp

/workspace 地图解释：

  • 左侧($(pwd))是主机上的一个文件夹。
  • 右侧(/workspace)是容器内的路径。
  • 此MCP服务器运行的命令应针对以下文件 /workspace；这些更改将写回映射的主机文件夹。

对于Docker中的HTTP模式，绑定到 0.0.0.0 并发布端口 -p。如果将容器暴露在localhost之外，请设置 BASH_COMMAND_MCP_ALLOWED_HOSTS 您要允许的主机名。

例子：

  • 如果你的主人有 ./project/file.txt 然后从以下位置运行容器 ./project，容器中也有相同的文件 /workspace/file.txt.

相关 MCP