接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @nickw8/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
BASH_MCP_MODE=<value> BASH_MCP_PROFILE=<value> BASH_MCP_RESPONSE_MODE=<value> claude mcp add io.github.nickw8-bash-mcp -- npx -y @nickw8/bash-mcp@5.0.1在終端機中執行。
{ "mcpServers": { "io.github.nickw8-bash-mcp": { "command": "npx", "args": [ "-y", "@nickw8/[email protected]" ], "env": { "BASH_MCP_MODE": "<value>", "BASH_MCP_PROFILE": "<value>", "BASH_MCP_RESPONSE_MODE": "<value>" } } }}claude_desktop_config.json
遠端 URL 還是本機指令？ 兩種安裝方式的差異
來自發布者
An MCP server that wraps common CLI tools (kubectl, terraform, helm, git, argocd, jq, yq, ripgrep, etc.) and returns structured JSON instead of raw text output.
Designed for AI agents and LLM-powered workflows where parsing human-readable CLI output wastes tokens and breaks easily.
Created with the help of Claude since it is the main consumer of the structured data.
Structured JSON wrappers for git, kubectl, terraform, helm, argocd, gh, glab and other CLIs.
No installation needed — just add the MCP config and npx will fetch it on first use.
npm install -g @nickw8/bash-mcp
git clone https://github.com/nickw8/bash-mcp.git
cd bash-mcp
npm install && npm run build
npm link
Run the built-in preflight check before wiring bash-mcp into a client:
npx -y @nickw8/bash-mcp --doctor # or: bash-mcp --doctor (global install)
It reports your Node version, whether the MCP SDK loads, which CLIs are
available (versions included), and the resolved BASH_MCP_MODE — then exits
non-zero if a critical check fails (Node too old or the SDK can't load). Missing
CLIs are advisory, not failures. Without --doctor, the binary starts the MCP
server as usual.
Add bash-mcp to your Claude Code settings. For all projects (recommended), edit ~/.claude/settings.json. For a single project, edit .claude/settings.json in the project root.
With npx (no install required):
{
"mcpServers": {
"bash-mcp": {
"command": "npx",
"args": ["-y", "@nickw8/bash-mcp"],
"env": {
"BASH_MCP_MODE": "readOnly"
}
}
}
}
Safe by default: an unset
BASH_MCP_MODEresolves toreadOnly, which blocks mutatingrun/batchcommands. The examples set it explicitly for clarity. For trusted local use, setBASH_MCP_MODE=offto allow writes.
With global install:
{
"mcpServers": {
"bash-mcp": {
"command": "bash-mcp",
"env": {
"BASH_MCP_MODE": "readOnly"
}
}
}
}
To verify it's working, start Claude Code and check that bash-mcp tools (like cat, rg, git_status) appear in the tool list.
You can also add it from the CLI:
claude mcp add bash-mcp -e BASH_MCP_MODE=readOnly -- npx -y @nickw8/bash-mcp
Registering the server exposes the tools, but agents still reach for raw Bash
out of habit. Two assets fix that: a rules file (~/.claude/rules/bash-mcp-tools.md,
auto-loaded into every session — the tool inventory) and a PreToolUse(Bash)
redirect hook. Install both with:
npx -y @nickw8/bash-mcp --install-claude # copy into ~/.claude
npx -y @nickw8/bash-mcp --install-claude --check # report drift, write nothing
It prints the settings.json hook block to paste in (the rules file needs no
settings — Claude Code auto-loads ~/.claude/rules/*.md). See
hooks/README.md for details and the clone-time
npm run claude:install equivalent. --uninstall-claude removes both files again.
Or install the Claude Code plugin, which bundles the server and the hook (in warn
mode — it never blocks unless BASH_MCP_HOOK=block):
/plugin install bash-mcp --marketplace nickw8/bash-mcp
Every other client (VS Code/Copilot, Codex, generic stdio) and pinned versions: docs/guides/installation.md.
Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/,
Windows: %APPDATA%\Claude\) and add the same mcpServers entry:
{
"mcpServers": {
"bash-mcp": {
"command": "npx",
"args": ["-y", "@nickw8/bash-mcp"],
"env": {
"BASH_MCP_MODE": "readOnly"
}
}
}
}
Restart Claude Desktop after editing.
Add bash-mcp to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):
{
"mcpServers": {
"bash-mcp": {
"command": "npx",
"args": ["-y", "@nickw8/bash-mcp"],
"env": {
"BASH_MCP_MODE": "readOnly"
}
}
}
}
(Use "command": "bash-mcp" with no args if you installed globally.) Any MCP-aware
client works the same way — point it at the bash-mcp binary or npx -y @nickw8/bash-mcp.
Optional Claude Code hooks in hooks/ steer agents toward the structured tools by blocking raw shell commands (git status, kubectl get, cat, …) that have a bash-mcp equivalent, while letting write commands (git commit, kubectl apply) pass through. BASH_MCP_HOOK=warn makes every block advisory; off disables the hook.
See docs/runbooks/hooks-setup.md for setup.
Raw CLI tools return text meant for humans. AI agents waste tokens parsing tables, aligning columns, and guessing field boundaries. bash-mcp runs the same CLI tools but returns structured JSON with typed schemas, so the agent gets exactly the data it needs.
# 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", ... }
See docs/guides/token-benchmarks.md for measured savings (e.g.
kubectl describe pod → kube_diagnose_pod is ~64% fewer tokens).
run is the escape hatchkube_diagnose_pod,
helm_release_triage, and argo_app_health_summary answer an operational question
in one call — { status, likelyCauses, suggestedNextCommands, evidence } — instead of
making the agent run get, then logs, then reason across both.run / batch are the escape hatch. For commands without a dedicated wrapper,
run executes anything with smart truncation. Optional hooks actively steer
agents back to the structured tool when a raw equivalent is invoked.Read-only tools carry the MCP readOnlyHint annotation. run/batch can be gated with
BASH_MCP_MODE (see Configuration).
Pick the structured tool that matches your intent instead of reaching for a raw command.
The list_guidance tool returns this same index as JSON (filter by intent or category),
so agents can self-select without the README.
📖 Full tool reference →
docs/tools.md— generated from the registered tools (inputs, outputs, and the raw command each one approximates). Regenerate withnpm run docs:tools.
All tf_* tools accept binary: "terraform" | "tofu" (or set $TF_BINARY) to run OpenTofu.
Triage a crash-looping pod. Before — three raw calls plus reasoning:
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
After — one structured call:
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"] }
Review a feature branch. Before: git log main..HEAD, git diff --stat main...HEAD,
git diff main...HEAD — three commands, manual stitching. After:
git_pr_context(base="main")
→ { commits: [...], files: [...], summary: { filesChanged, insertions, deletions } }
Check capabilities before acting. Instead of which kubectl && kubectl config current-context:
check_environment()
→ { kubectl: { installed: true, version: "1.31.2", context: "prod" },
terraform: { installed: false }, ... }
Each tool group uses appropriate default timeouts:
All commands default to a 10 MB output buffer. Override per-tool in 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
Each tool file exports a single register*Tools(server) function that registers all tools in its group. Every tool returns both content (text for display) and structuredContent (typed JSON for programmatic use).
src/tools/<group>/<group>.ts) or create a new category directoryannotations: { readOnlyHint: true } for read-only tools)exec() or execJson() from #exec, return ok() or err() from #responsedefineTool from #tool (injects wide-event logging + uniform error catching)register*Tools into src/index.ts*.test.ts fileimport { 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() });
});
}
See docs/guides/adding-tools.md for the full guide.
The following CLI tools must be installed for their respective tool groups to work:
ls, tree, find, du, rg (ripgrep)gitkubectlterraform or tofuhelmargocdjqyq (mikefarah/yq)dotnet (.NET SDK)liquibaseruff (lint), mypy (typecheck), pytest (test)Tools gracefully return errors if their underlying CLI is not installed.
Apache-2.0
Structured JSON wrappers for git, kubectl, terraform, helm, argocd, gh, glab and other CLIs.
{ "mcpServers": { "io.github.nickw8-bash-mcp": { "command": "npx", "args": [ "-y", "@nickw8/[email protected]" ], "env": { "BASH_MCP_MODE": "<value>", "BASH_MCP_PROFILE": "<value>", "BASH_MCP_RESPONSE_MODE": "<value>" } } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式，而不是 PlugMCP 代理伺服器。
發布者列出了以下環境變數：BASH_MCP_MODE, BASH_MCP_PROFILE, BASH_MCP_RESPONSE_MODE。
Bash 透過 stdio 在本機執行。
上次檢查時間：2026-11-10。 Structured JSON wrappers for git, kubectl, terraform, helm, argocd, gh, glab and other CLIs.