bash-mcp server

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

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

clarity. For trusted local use, set BASHMCPMODE=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 BASHMCPHOOK=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 claudedesktopconfig.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):

Shortened. The full README is on GitHub.