Bash

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 — 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

Kubernetes

Terraform

Helm

ArgoCD

Data Processing

.NET

Liquibase

Node.js

Python

Shell

Execution

Results

All tf_* tools accept binary: "terraform" | "tofu" (or set $TF_BINARY) to run OpenTofu.

Example Agent Workflows

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 }, ... }

Configuration

Environment Variables

Timeouts

Each tool group uses appropriate default timeouts:

• Filesystem/search/git: 30 seconds
• Kubernetes/Helm/ArgoCD: 15 seconds
• Terraform state: 30 seconds
• Terraform plan: 120 seconds
• .NET build/test: 120 seconds
• Python lint: 30 seconds
• Python test: 120 seconds
• Python typecheck: 60 seconds

Command Buffer

All commands default to a 10 MB output buffer. Override per-tool in src/exec.ts.

Development

# 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

Architecture

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

Adding a New Tool

1. Add to an existing category (src/tools/<group>/<group>.ts) or create a new category directory
2. Define input/output schemas with Zod (add annotations: { readOnlyHint: true } for read-only tools)
3. Implement the handler using exec() or execJson() from #exec, return ok() or err() from #response
4. Register it with defineTool from #tool (injects wide-event logging + uniform error catching)
5. Wire the group's register*Tools into src/index.ts
6. Add tests in a co-located *.test.ts file

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() });
  });
}

See docs/guides/adding-tools.md for the full guide.

Prerequisites

The following CLI tools must be installed for their respective tool groups to work:

• Always required: Node.js >= 20
• Filesystem/search: ls, tree, find, du, rg (ripgrep)
• Git: git
• Kubernetes: kubectl
• Terraform/OpenTofu: terraform or tofu
• Helm: helm
• ArgoCD: argocd
• JSON: jq
• YAML: yq (mikefarah/yq)
• .NET: dotnet (.NET SDK)
• Liquibase: liquibase
• Python: ruff (lint), mypy (typecheck), pytest (test)

Tools gracefully return errors if their underlying CLI is not installed.

License

Apache-2.0