bash-mcp

bash-mcp

一个 MCP 服务，用于封装常见的 CLI 工具（kubectl、terraform、helm、git、argocd、jq、yq、ripgrep 等），并返回结构化 JSON，而非原始文本输出。

专为 AI Agent 和由大模型驱动的工作流设计，可避免解析人类可读的 CLI 输出所浪费的 token，以及由此带来的不稳定问题。

在 Claude 的帮助下创建，因为 Claude 是结构化数据的主要使用者。

快速开始

选项 1：使用 npx，无需安装

无需安装——只需添加 MCP 配置，npx 就会在首次使用时获取它。

选项 2：全局安装

npm install -g @nickw8/bash-mcp

选项 3：从源代码安装

git clone https://github.com/nickw8/bash-mcp.git
cd bash-mcp
npm install && npm run build
npm link

验证设置

将 bash-mcp 接入客户端之前，先运行内置的预检：

npx -y @nickw8/bash-mcp --doctor   # or: bash-mcp --doctor (global install)

它会报告 Node 版本、MCP SDK 是否可加载、哪些 CLI 可用（包括版本），以及解析后的 BASH_MCP_MODE；如果关键检查失败（Node 版本过旧或 SDK 无法加载），则以非零状态码退出。缺少 CLI 仅作提示，不会导致失败。不使用 --doctor 时，程序会照常启动 MCP 服务。

Claude Code 设置

将 bash-mcp 添加到 Claude Code 设置中。若要用于所有项目（推荐），请编辑 ~/.claude/settings.json。若要用于单个项目，请编辑项目根目录下的 .claude/settings.json。

使用 npx（无需安装）：

{
  "mcpServers": {
    "bash-mcp": {
      "command": "npx",
      "args": ["-y", "@nickw8/bash-mcp"],
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

默认安全： 未设置 BASH_MCP_MODE 时，其值会解析为 readOnly，从而阻止会修改内容的 run/batch 命令。示例中显式设置了该变量，以便说明。若在可信的本地环境中使用，可设置 BASH_MCP_MODE=off 以允许写入。

使用全局安装：

{
  "mcpServers": {
    "bash-mcp": {
      "command": "bash-mcp",
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

要验证是否正常工作，请启动 Claude Code，并检查工具列表中是否出现 bash-mcp 工具（如 cat、rg、git_status）。

也可以通过 CLI 添加：

claude mcp add bash-mcp -e BASH_MCP_MODE=readOnly -- npx -y @nickw8/bash-mcp

引导 Agent 使用结构化工具（可选）

注册服务后，工具便会公开，但 Agent 仍会习惯性地使用原始 Bash。两项配置可解决这一问题：一个规则文件（~/.claude/rules/bash-mcp-tools.md，会自动加载到每个会话中，列出可用工具）和一个 PreToolUse(Bash) 重定向钩子。使用以下命令安装这两项配置：

npx -y @nickw8/bash-mcp --install-claude        # copy into ~/.claude
npx -y @nickw8/bash-mcp --install-claude --check # report drift, write nothing

命令会输出 settings.json 钩子配置块，供你粘贴进去（规则文件无需设置——Claude Code 会自动加载 ~/.claude/rules/*.md）。详情及克隆时使用的等效命令 npm run claude:install，请参阅 hooks/README.md。--uninstall-claude 会移除这两个文件。

也可以安装 Claude Code 插件，它包含该服务和钩子（处于 warn 模式——除非设置了 BASH_MCP_HOOK=block，否则不会阻止命令）：

/plugin install bash-mcp --marketplace nickw8/bash-mcp

其他客户端（VS Code/Copilot、Codex、通用 stdio）及固定版本的相关说明，请参阅： docs/guides/installation.md。

Claude Desktop 设置

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/， Windows：%APPDATA%\Claude\），并添加相同的 mcpServers 条目：

{
  "mcpServers": {
    "bash-mcp": {
      "command": "npx",
      "args": ["-y", "@nickw8/bash-mcp"],
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

编辑后重启 Claude Desktop。

Cursor 设置

将 bash-mcp 添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（每个项目）：

{
  "mcpServers": {
    "bash-mcp": {
      "command": "npx",
      "args": ["-y", "@nickw8/bash-mcp"],
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

（如果已全局安装，请在 "command": "bash-mcp" 中省略参数。）任何支持 MCP 的客户端都可以采用相同方式使用——将其指向 bash-mcp 二进制文件或 npx -y @nickw8/bash-mcp。

推荐的钩子

hooks/ 中可选的 Claude Code 钩子会引导 Agent 使用结构化工具：对于存在 bash-mcp 对应工具的原始 shell 命令（git status、kubectl get、cat 等）予以阻止，同时允许写入命令（git commit、kubectl apply）通过。BASH_MCP_HOOK=warn 会将所有阻止操作设为提示；off 则会禁用钩子。

设置说明请参阅 docs/runbooks/hooks-setup.md。

为什么要使用结构化输出？

原始 CLI 工具返回的是面向人类的文本。AI Agent 会浪费 token 来解析表格、对齐列并猜测字段边界。bash-mcp 运行相同的 CLI 工具，但返回带类型架构的结构化 JSON，因此 Agent 能准确获取所需数据。

# Raw kubectl output: 148 tokens to parse a table
NAME                     READY   STATUS    RESTARTS   AGE
nginx-7c5b8d6c88-abc12  1/1     Running   0          3d

# bash-mcp output: typed, compact, ready to use
{ "name": "nginx-7c5b8d6c88-abc12", "status": "Running", "age": "3d", ... }

如需查看实测节省量（例如，kubectl describe pod → kube_diagnose_pod 可减少约 64% 的 token），请参阅 docs/guides/token-benchmarks.md。

理念：优先使用结构化工具，run 是备用方案

1. 优先使用结构化工具。 每个包装器都会返回 Agent 可直接使用的带类型 JSON——无需计数列数，也无需在格式变更时重新解析。
2. 优先使用诊断工具，而非串联原始命令。 kube_diagnose_pod、helm_release_triage 和 argo_app_health_summary 等工具可通过一次调用回答运维问题——{ status, likelyCauses, suggestedNextCommands, evidence }——而不必让 Agent 先运行 get，再运行 logs，然后综合两者进行推理。
3. run / batch 是备用方案。 对于没有专用包装器的命令，run 可以执行任何命令，并进行智能截断。可选的 hooks 会主动引导 Agent：当调用原始命令的等效工具时，转而使用结构化工具。

只读工具带有 MCP readOnlyHint 注释。可以通过 BASH_MCP_MODE 限制 run / batch（参见配置）。

我应该使用哪个工具？

请根据你的意图选择合适的结构化工具，而不是直接使用原始命令。 list_guidance 工具会以 JSON 格式返回同一索引（可按 intent 或 category 筛选）， 让 Agent 无需查看 README 即可自行选择。

我想……	使用此工具	而不是
诊断崩溃或失败的 Kubernetes Pod	kube_diagnose_pod	kubectl describe pod、kubectl logs
查找命名空间中所有未就绪或失败的 Pod	kube_pod_failure_summary	kubectl get pods、kubectl get pods | grep
检查 Deployment 的发布状态	kube_deployment_status	kubectl rollout status、kubectl get deployment
了解集群近期事件	kube_events_summary	kubectl get events
汇总 Terraform 计划中的变更	tf_plan_summary	terraform plan、terraform show
在创建 PR 前审查当前功能分支	git_pr_context	git diff、git log、git status
了解仓库的整体状态	repo_health_summary	git status、git log --oneline
查看文件结构而不加载完整内容	outline	cat (整个文件)、cat
阅读大型文件中的某个区域	cat	cat (整个文件)、sed -n '10,40p'
避免宽泛搜索内容淹没上下文	rg	rg | head
搜索精确的代码引用或符号	rg	grep -r、rg
检查拉取请求的 CI 检查是否通过	gh_pr_checks	gh pr checks、gh pr view
查明 CI / GitHub Actions 运行失败的原因	gh_run_failure_summary	gh run view --log-failed、gh run list
检查 GitLab 流水线或合并请求的作业是否通过	glab_ci_status	glab ci get、glab ci status
查明 GitLab CI 流水线失败的原因	glab_pipeline_failure_summary	glab ci trace、glab ci view
排查 Helm 发布状态异常的原因	helm_release_triage	helm status、helm get values
检查 ArgoCD 应用是否健康且同步	argo_app_health_summary	argocd app get、argocd app list
验证 Liquibase 变更日志是否有错误	liquibase_validate	liquibase validate
预览 Liquibase 将为待处理变更集运行的 SQL	liquibase_update_sql	liquibase updateSQL、liquibase updateSQL | grep
列出尚未应用到数据库的 Liquibase 变更集	liquibase_status	liquibase status --verbose
检查 Shell 脚本中的错误和引号问题	bash_lint	shellcheck、shellcheck -f json1
运行 bats 或 Shell 测试套件	bash_test	bats、bash test.sh
调用工具前查明已安装哪些 CLI	check_environment	which、<tool> --version

工具

📖 完整工具参考 → docs/tools.md — 根据已注册的工具生成 （包括输入、输出，以及每个工具近似替代的原始命令）。 使用 npm run docs:tools 重新生成。

环境

工具	描述
check_environment	报告已安装的 CLI 及其版本，以便你在调用前选择合适的工具。
list_guidance	返回意图 → 首选工具索引，帮助你根据目标选择合适的 bash-mcp 工具。

文件系统

工具	描述
ls	列出目录中的文件。
tree	以紧凑的树形结构显示目录结构。
du	显示路径的磁盘使用情况。
find_files	按名称模式、类型或修改时间查找文件。

搜索

工具	描述
rg	使用 ripgrep 搜索文件内容。
glob	查找与 glob 模式匹配的文件。

文件

工具	描述
cat	读取一个或多个文件，显示行号并智能截断内容。
outline	显示文件的结构大纲——函数/类名称、顶层注释和导入项。

Git

工具	描述
git_status	结构化的 Git 状态：分支、已暂存／未暂存／未跟踪的文件。
git_log	结构化的 Git 日志：提交哈希、作者、日期、消息。
git_diff	结构化的 Git 差异：已更改文件及新增／删除行数。
git_branches	列出 Git 分支。
repo_health_summary	一次调用即可概览 Git 工作树：分支、相对上游的领先／落后状态、已暂存／未暂存／未跟踪文件数量、近期提交，以及未提交更改的差异统计。
git_pr_context	收集分支相对于基础引用的提交和文件更改（用于编写 PR 描述）：提交列表、带状态的已更改文件，以及从基础引用到分支头的差异统计。
git_diff_content	显示包含结构化补丁内容的 Git 差异。

GitHub

工具	描述
gh_pr_checks	按状态统计拉取请求的 CI 检查，并报告失败和待处理的检查。
gh_run_failure_summary	一次调用即可诊断 GitHub Actions 运行：状态、失败的作业和步骤，以及失败日志中作为证据的 ##[error] 行。

GitLab

工具	描述
glab_ci_status	按状态统计 GitLab 流水线的作业，并报告失败、运行中和待处理的作业。
glab_pipeline_failure_summary	一次调用即可诊断 GitLab 流水线：状态、失败的作业及 GitLab 给出的失败原因，以及各个失败作业跟踪日志中作为证据的末尾脚本行。

Kubernetes

工具	描述
kube_get	以结构化数据的形式获取 Kubernetes 资源。
kube_logs	获取 Pod 日志。
kube_contexts	列出可用的 kubectl 上下文，并标记当前上下文。
kube_diagnose_pod	一次调用即可诊断 Pod 不健康的原因。
kube_pod_failure_summary	列出命名空间中的不健康 Pod，并提供失败原因和证据——一次调用即可，无需对每个 Pod 分别执行 get 和 describe。
kube_deployment_status	以结构化诊断的形式报告 Deployment 的发布健康状况（就绪／期望副本数、状态）。
kube_events_summary	汇总命名空间中的 Warning 事件（按原因分组，并按数量排序），无需滚动查看原始的 kubectl get events 输出。

Terraform

工具	描述
tf_state_list	列出 Terraform 状态中的资源。
tf_show	以结构化 JSON 的形式显示当前 Terraform 状态。
tf_plan_summary	运行 terraform plan，并返回变更的结构化摘要（新增／更改／销毁数量及受影响的资源）。
tf_workspaces	列出 Terraform 工作区，并标记当前工作区。
tf_outputs	以 [名称，值] 对的形式列出 Terraform/OpenTofu 输出；敏感输出仅显示为 [名称]。
tf_providers	列出项目的 Terraform/OpenTofu 版本及已选定的提供程序版本。
tf_validate_summary	验证 Terraform/OpenTofu 配置，并返回包含诊断信息的简要通过／失败摘要。
tf_modules_summary	列出已初始化的 Terraform/OpenTofu 项目所用模块（键、来源、版本）。
tf_backend_info	报告已初始化项目配置的后端类型和配置。

Helm

工具	描述
helm_list	列出 Helm 发布及其状态、Chart 和应用版本。
helm_status	获取 Helm 发布的详细状态。
helm_values	以结构化数据的形式获取 Helm 发布的计算后取值。
helm_release_triage	一次调用即可诊断 Helm 发布的健康状况：结合 helm status 和 helm history，提供当前状态、可能原因、建议的后续命令，以及近期修订的证据。

ArgoCD

工具	描述
argo_apps	列出 ArgoCD 应用及其同步／健康状态。
argo_app_detail	获取单个 ArgoCD 应用的详细状态，包括资源健康状况。
argo_app_diff	显示 ArgoCD 应用中不同步的内容。
argo_app_health_summary	通过一次调用诊断 ArgoCD 应用的健康状况：整体同步／健康状态、可能原因、建议执行的下一条命令，以及作为依据的不健康资源／条件。

数据处理

工具	描述
jq	使用 jq 表达式查询和转换 JSON。
yq	使用 yq 表达式（mikefarah/yq）查询和转换 YAML 文件。

.NET

工具	描述
dotnet_build	运行 dotnet build，并返回结构化诊断信息，包括文件、行、列、消息和错误代码。
dotnet_test	运行 dotnet test，并返回结构化结果：通过／失败／跳过数量、失败消息。

Liquibase

工具	描述
liquibase_validate	验证 Liquibase 变更日志，并返回结构化的通过／失败结果，以及每个变更集的错误（重复 ID、校验和漂移）。
liquibase_update_sql	将 Liquibase 对待处理变更集执行的 SQL（updateSQL）呈现为结构化的逐变更集摘要，并进行 SQL-Server 批次 lint 检查。
liquibase_status	以结构化 JSON 列出尚未应用于目标数据库的 Liquibase 变更集。

Node.js

工具	描述
npm_lint	运行 biome check，并返回结构化诊断信息，包括文件、行、列、消息和规则。
npm_test	运行 vitest 或 jest（根据 package.json 选择），并返回结构化测试结果：套件、通过／失败数量、失败消息。
npm_typecheck	运行 tsc/tsgo --noEmit，并返回结构化类型错误，包括文件、行、列、消息和 TS 错误代码。

Python

工具	描述
python_lint	运行 ruff check，并返回结构化诊断信息，包括文件、行、列、消息和规则代码。
python_test	运行 pytest，并返回结构化测试结果：套件、通过／失败数量、失败消息。
python_typecheck	运行 mypy，并返回结构化类型错误，包括文件、行、列、消息和错误代码。

Shell

工具	描述
bash_syntax_check	使用 bash -n 检查 shell 脚本是否存在语法错误，并返回结构化诊断信息（文件、行、消息）。
bash_lint	运行 shellcheck，并返回结构化诊断信息，包括文件、行、列、消息和 SC 规则代码。
bash_test	运行 shell 测试脚本——通过 --tap 运行 bats .bats 文件，或运行普通 .sh 测试框架——并返回结构化结果：每个测试用例的通过／失败情况，以及从 TAP 或 N tests, M failures 输出中解析出的摘要；若格式无法识别，则仅返回退出代码。

执行

工具	描述
run	运行单条命令——由一个二进制文件和一个参数数组组成，直接执行而不使用 shell（因此字符串中不能包含管道、重定向或 ';'/'&&'）——并返回经过智能截断的结构化输出。
run_seq	按顺序逐个运行一组带标签的命令，默认在首次失败时停止。
batch	并行运行多条命令并返回所有结果。

结果

工具	描述
result_get	分页获取响应预算截断的结果。

所有 tf_* 工具都接受 binary: "terraform" | "tofu"（或设置 $TF_BINARY）以运行 OpenTofu。

Agent 工作流示例

排查崩溃循环的 Pod。 之前——三次原始调用加推理：

kubectl get pods -n payments          # find the broken pod
kubectl describe pod api-xyz          # read events/state, infer cause
kubectl logs api-xyz --tail=200       # scroll for the error
# ...agent reasons across all three to guess the next step

之后——一次结构化调用：

kube_diagnose_pod(pod="api-xyz", namespace="payments")
→ { status: "CrashLoopBackOff",
    likelyCauses: ["container exits 1; DB connection refused"],
    suggestedNextCommands: ["kube_logs(pod='api-xyz', container='api')"],
    evidence: ["Restart Count: 12", "BackOff x140 over 30m"] }

审查功能分支。 之前：git log main..HEAD、git diff --stat main...HEAD、 git diff main...HEAD——三条命令，手动整合。之后：

git_pr_context(base="main")
→ { commits: [...], files: [...], summary: { filesChanged, insertions, deletions } }

操作前检查功能。 使用 which kubectl && kubectl config current-context 的替代方式：

check_environment()
→ { kubectl: { installed: true, version: "1.31.2", context: "prod" },
    terraform: { installed: false }, ... }

配置

环境变量

变量	可选值	默认值	效果
BASH_MCP_LOG	error | info | off	error	将宽事件 JSON 日志写入 stderr（每次工具调用一行）。error 仅记录失败的调用；info 还会记录成功调用；off/silent 则禁用日志。stdout 始终保持纯 MCP 输出。run/batch 命令会脱敏（仅保留元数据）。
BASH_MCP_MODE	readOnly | confirmWrites | off	readOnly	控制 run/batch。默认的 readOnly 会阻止被判定为会更改数据的命令（confirmWrites 同样如此）。设置为 off（或 dangerous）可禁用强制执行——仅建议在可信的本地环境中使用。
BASH_MCP_PROFILE	core | development | infrastructure | all	all	注册哪些工具组。工具越少，上下文中的 schema 就越少——参见工具发现。未知值会导致启动失败。
BASH_MCP_RESPONSE_MODE	auto | summary | compact | full	auto	响应预算。被截断的结果会带有 retained，其完整负载可通过 result_get 分页获取。full 是 v4 的行为。参见输出约定。
BASH_MCP_RESULT_TTL	秒	900	已存储结果的可检索时长；0 表示禁用存储。
BASH_MCP_HOOK	block | warn | off	block（插件中为 warn）	重定向钩子的行为。
TF_BINARY	terraform | tofu	terraform	所有 tf_* 工具的默认二进制文件（可通过每次调用时的 binary 覆盖）。

超时

每个工具组都使用适当的默认超时时长：

• 文件系统/搜索/git：30 秒
• Kubernetes/Helm/ArgoCD：15 秒
• Terraform 状态：30 秒
• Terraform 计划：120 秒
• .NET 构建/测试：120 秒
• Python lint：30 秒
• Python 测试：120 秒
• Python 类型检查：60 秒

命令缓冲区

所有命令默认使用 10 MB 输出缓冲区。可在 src/exec.ts 中按工具覆盖。

开发

# Install dependencies
npm install

# Run in development mode (auto-reloads)
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test

# Lint and format
npm run lint
npm run format

架构

src/
  index.ts              # Server entry point — registers tools and starts stdio transport
  exec.ts               # Command execution layer — runs CLI tools via execFile
  tool.ts               # defineTool — wraps registerTool with wide-event logging + error catching
  error.ts              # ToolError taxonomy + classifyError (missing_binary, timeout, ...)
  logger.ts             # Zero-dep structured stderr logger (BASH_MCP_LOG)
  safety.ts             # Command classification + BASH_MCP_MODE gate for run/batch
  format.ts             # Multi-format list output (TSV, columnar, JSON)
  response.ts           # MCP response helpers (ok, okList, err)
  shell.ts              # Shell escaping utilities
  parsers/
    types.ts            # Shared interfaces: Diagnostic, TestResult, TestSuite
    schemas.ts          # Shared Zod (diagnostic, budget fragment, applyBudget)
  tools/
    argocd/argocd.ts    # argo_apps, argo_app_detail, argo_app_diff
    batch/batch.ts      # batch (parallel command execution)
    dotnet/
      dotnet.ts         # dotnet_build, dotnet_test
      parsers/          # MSBuild and TRX output parsers
    file/
      file.ts           # cat (file reading with metadata), outline (structural file outline)
      outline/          # Language-specific outline extractors
    filesystem/
      filesystem.ts     # ls, tree, du, find_files
    git/
      git.ts            # git_status, git_log, git_diff, git_branches
      diff.ts           # git_diff_content (structured patch hunks)
    helm/helm.ts        # helm_list, helm_status, helm_values
    json/json.ts        # jq
    kubernetes/
      kubernetes.ts     # kube_get, kube_logs, kube_contexts
    npm/
      npm.ts            # npm_lint, npm_test, npm_typecheck
      parsers/          # Biome, Vitest, tsc output parsers
    run/run.ts          # run (command execution with smart truncation)
    search/search.ts    # rg, glob
    terraform/
      terraform.ts      # tf_state_list, tf_show, tf_plan_summary, tf_workspaces
    yaml/yaml.ts        # yq

每个工具文件都会导出一个 register*Tools(server) 函数，用于注册其工具组中的所有工具。每个工具都会同时返回 content（用于显示的文本）和 structuredContent（供程序化使用的类型化 JSON）。

添加新工具

1. 添加到现有类别（src/tools/<group>/<group>.ts），或新建类别目录
2. 使用 Zod 定义输入/输出 schema（只读工具添加 annotations: { readOnlyHint: true }）
3. 使用 #exec 中的 exec() 或 execJson() 实现处理程序，并从 #response 返回 ok() 或 err()
4. 使用 #tool 中的 defineTool 注册（注入宽事件日志记录和统一的错误捕获）
5. 将该组的 register*Tools 接入 src/index.ts
6. 在同目录的 *.test.ts 文件中添加测试

import { z } from "zod";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { exec } from "#exec";
import { ok, err } from "#response";
import { defineTool } from "#tool";

export function registerMyTools(server: McpServer) {
  defineTool(server, "my_tool", {
    title: "My tool",
    description: "What it does and why structured output helps.",
    inputSchema: {
      path: z.string().describe("Path to operate on"),
    },
    outputSchema: {
      result: z.string(),
    },
    annotations: { readOnlyHint: true },
  }, async ({ path }) => {
    const result = await exec("mytool", ["--json", path]);

    if (result.exitCode !== 0) {
      return err(result.stderr, { result: "" });
    }

    return ok({ result: result.stdout.trim() });
  });
}

完整指南请参见 docs/guides/adding-tools.md。

前置条件

以下 CLI 工具必须已安装，相应工具组才能正常工作：

• 始终必需：Node.js >= 20
• 文件系统/搜索：ls、tree、find、du、rg（ripgrep）
• Git：git
• Kubernetes：kubectl
• Terraform/OpenTofu：terraform 或 tofu
• Helm：helm
• ArgoCD：argocd
• JSON：jq
• YAML：yq（mikefarah/yq）
• .NET：dotnet（.NET SDK）
• Liquibase：liquibase
• Python：ruff（lint）、mypy（类型检查）、pytest（测试）

如果底层 CLI 未安装，工具会妥善返回错误。

许可证

Apache-2.0