Bash Command MCP

bash命令mcp

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

重要安全警告

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

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

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

bun install

要运行：

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

码头工人

塑造形象：

docker build -t bash-command-mcp .

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

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

/workspace 地图解释：

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

例子：

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