bash-command-mcp

bash-command-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 日志文件。
• 提供 OpenTelemetry 跟踪和指标，支持生产环境可视化。
• 符合 Agent 使用习惯，可通过 cwd 和 env 覆盖项精确指定执行上下文。

工具行为

工具：

• run：在前台运行命令。 参数：command 或 cmd、timeoutSeconds（默认值为 60，最小值为 1；超过 86400 的值会被限制，并给出提示），可选的 cwd、可选的 env。
• run_background：在后台启动命令，并将 stdout/stderr 写入日志文件。 参数：command 或 cmd、可选的 cwd、可选的 env。
• list_background：列出已跟踪的后台进程，包括日志文件路径。
• kill_background：根据 pid 停止已跟踪的后台进程。
• tail_background：显示后台进程日志的最后 N 行。 参数：pid、可选的 lines（默认值为 200，最大值为 5000）。
• wait_background：等待后台进程完成，并返回最终状态和输出。 参数：pid、可选的 timeoutSeconds（默认值为 60，最小值为 1；超过 86400 的值会被限制，并给出提示）。

OpenTelemetry

此服务内置了用于跟踪和指标的 OpenTelemetry 插桩。

• OpenTelemetry 软件包会随服务软件包一同安装。
• 除非设置了 OTEL_ENABLED=false，否则会初始化遥测功能。
• 如果设置了 OTEL_EXPORTER_OTLP_ENDPOINT，跟踪数据和指标会通过 OTLP HTTP 导出。
• 如果未配置 OTLP 端点，则使用控制台导出器。

插桩操作：

• run、run_background、list_background、tail_background、wait_background 和 kill_background 的工具调用 span。
• 后台生命周期 span/计数器（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 Collector）：

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，因此现有的桌面和命令行配置可以继续正常工作。

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 模式默认使用 Host 标头验证。如果绑定到 0.0.0.0 或 ::，请在 BASH_COMMAND_MCP_ALLOWED_HOSTS 中提供明确的允许列表。

Docker

构建镜像：

docker build -t bash-command-mcp .

将本地文件夹挂载到 /workspace 后运行：

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

通过 Streamable 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 访问同一文件。