bash-mcp

bash-mcp

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.

Quick Start

Option 1: Zero-install with npx

No installation needed — just add the MCP config and npx will fetch it on first use.

Option 2: Global install

npm install -g @nickw8/bash-mcp

Option 3: Install from source

git clone https://github.com/nickw8/bash-mcp.git

cd bash-mcp npm install && npm run build npm link

Verify your setup

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.

Claude Code Setup

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_MODE resolves to readOnly, which

blocks mutating run/batch commands. The examples set it explicitly for

clarity. For trusted local use, set BASH_MCP_MODE=off to 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

Steer agents toward the structured tools (optional)

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.

Claude Desktop Setup

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.

Cursor Setup

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.

Recommended Hooks

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.

Why Structured Output?

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).

Philosophy: structured tools first, run is the escape hatch

1. Reach for a structured tool first. Every wrapper returns typed JSON the agent can use directly — no column-counting, no re-parsing on a format change.
2. Prefer a diagnostic over a chain of raw commands. Tools like kube_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.
3. `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).

Which tool should I use?

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.

Tools

📖 [Full tool reference → `docs/tools.md`](docs/tools.md) — generated from the

registered tools (inputs, outputs, and the raw command each one approximates).

Regenerate with npm run docs:tools.

Environment

Filesystem

Search

File

Git

GitHub

GitLab

| glab_pipeline_failure_summary | Diagnose a GitLab pipeline in one call: status, the failed jobs and why GitLab says they failed, and the last script li