<!-- NOTE: README.md is generated from README.md.in. Edit README.md.in and run: bash scripts/render-readme.sh -->

mcp-bash

Repository: mcp-bash-framework  •  CLI/Binary: mcp-bash

For AI agents: Read llms.txt (compact) or llms-full.txt (detailed) for agent-optimized context — includes a step-by-step Quick Start, critical allowlist requirement, and CLI wrapper patterns.

Contents

• MCP Spec Coverage
• Why Bash?
• Quick Start
• Security Model (60 seconds)
• Configure Your MCP Client
• MCPB Bundles
• Vendoring the Runtime
• Project Structure
• Configuration
• Learn by Example
• Documentation
• Built with mcp-bash
• FAQ

The most complete MCP implementation in pure Bash. Tools, resources, prompts, elicitation, roots, progress, cancellation—the full spec, no runtimes beyond your shell.

• Runs on Bash 3.2+ (macOS/Linux stock). No Node, no Python, no containers.
• Handles concurrency, timeouts, and cancellation the way production systems need.
• You write the tools. The framework stays out of your way.

TL;DR

Turn any Bash script into an MCP tool in minutes. No Node, no Python, no containers.

mcp-bash new my-server && cd my-server
mcp-bash scaffold tool my-tool   # edit tools/my-tool/tool.sh
mcp-bash config --client cursor  # paste into your MCP client
mcp-bash bundle                  # create distributable package

What you’ll build

flowchart TD
  Client["MCP client<br/>(Claude Desktop / Cursor / Windsurf)"]
  Transport["stdio (JSON-RPC)"]
  Framework["mcp-bash framework<br/>(registry + runtime + policy)"]
  Project["Your project<br/>tools/ resources/ prompts/ server.d/"]

  Client --> Transport --> Framework --> Project

Design Principles

• Tools shouldn’t need another runtime to talk to AI.
• Everything must be inspectable. No magic.
• If it’s not needed in production, it isn’t in the framework.
• Your project stays yours. The framework upgrades cleanly.

MCP Spec Coverage

mcp-bash targets the 2025-11-25 MCP specification with negotiated downgrades to older versions.

| Category | Coverage | Notes | |----------|----------|-------| | Core Protocol | ✅ Full | Lifecycle, ping, capabilities, downgrades | | Tools | ✅ Full | list, call, icons, errors, listChanged, annotations | | Resources | ✅ Full | list, read, subscriptions, templates, binary, annotations | | Prompts | ✅ Full | list, get, arguments, icons | | Utilities | ✅ Full | Progress, cancellation, logging, completion | | Elicitation | ✅ Full | Form, URL, enum, multi-choice modes | | Roots | ✅ Full | Server→client request, listChanged | | MCP Apps (UI) | ⚠️ Partial | ui:// resources, templates; interactivity blocked by host bug |

Not yet implemented: Audio content, sampling. Tasks (async job/poll) and server-identity discovery are HTTP-oriented and not applicable to stdio.

Transport is stdio-only by design. See Remote Connectivity for HTTP/SSE proxy options, including the shared-secret guard (MCPBASH_REMOTE_TOKEN) and readiness probe (mcp-bash --health).

→ Full compliance matrix

For a complete feature-by-feature breakdown across all MCP versions, see the Feature Support Matrix in SPEC-COMPLIANCE.md.

Why Bash?

| | mcp-bash | TypeScript SDK | Python SDK | |---|----------|----------------|------------| | Runtime | Bash 3.2+ (pre-installed) | Node.js 18+ | Python 3.10+ | | Install | brew install or curl \| bash | npm install | pip install | | Startup | No VM warmup | Node.js startup | Python startup | | Dependencies | jq or gojq | npm packages | pip packages | | Best for | Shell automation, existing scripts, air-gapped/minimal environments | Node.js applications | Python applications |

If your tools are already shell scripts, wrapping them in Node or Python adds complexity for no benefit. mcp-bash lets you expose them directly.

Quick Start

When you run mcp-bash from inside a project (a directory containing server.d/server.meta.json), it auto-detects the project root. Running mcp-bash outside any project starts a temporary getting-started helper tool. For MCP clients, set MCPBASH_PROJECT_ROOT so the server can find your project regardless of working directory.

0. Requirements (10 seconds)

# Preflight: Bash 3.2+ and jq/gojq for full functionality (tools/resources/prompts).
bash --version | head -1
command -v jq >/dev/null 2>&1 || command -v gojq >/dev/null 2>&1 || printf '%s\n' '⚠ jq/gojq missing: minimal mode only (tools/resources/prompts disabled)'

1. Install the Framework

Homebrew (macOS and Linux — recommended):

brew install yaniv-golan/mcp-bash/mcp-bash

Update later with brew upgrade mcp-bash.

curl installer (CI, Docker, Windows/Git Bash, or environments without Homebrew):

curl -fsSL "https://raw.githubusercontent.com/yaniv-golan/mcp-bash-framework/v1.3.0/install.sh" | bash -s -- --yes --version "v1.3.0"

Verified install (recommended for production / security-sensitive environments):

version="v1.3.0"
file="mcp-bash-${version}.tar.gz"
curl -fsSLO "https://github.com/yaniv-golan/mcp-bash-framework/releases/download/${version}/${file}"
curl -fsSLO "https://github.com/yaniv-golan/mcp-bash-framework/releases/download/${version}/SHA256SUMS"

# Verify (macOS):
grep -E "([[:space:]]|\\*)${file}$" SHA256SUMS | shasum -a 256 -c -
# Verify (Linux):
grep -E "([[:space:]]|\\*)${file}$" SHA256SUMS | sha256sum -c -

curl -fsSLO "https://raw.githubusercontent.com/yaniv-golan/mcp-bash-framework/${version}/install.sh"
bash install.sh --archive "${file}" --version "${version}"

Why this is “verified”: you download the release tarball + SHA256SUMS, verify the checksum locally, then run the installer against the verified archive.

For tagged releases (vX.Y.Z), the installer also attempts to verify the archive against SHA256SUMS automatically when it’s available.

Manual/offline install (for policy-driven or air-gapped environments):

git clone https://github.com/yaniv-golan/mcp-bash-framework.git ~/.local/share/mcp-bash
mkdir -p ~/.local/bin && ln -sf ~/.local/share/mcp-bash/bin/mcp-bash ~/.local/bin/mcp-bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc (if not already in PATH)

Pin a release with the installer (auto-prefixes v for bare versions):

bash install.sh --verify <sha256-from-SHA256SUMS> --version 1.3.0

1.5 Verify It Works (30 seconds)

Security defaults: hooks are disabled unless MCPBASH_ALLOW_PROJECT_HOOKS=true, and tools require an explicit allowlist (MCPBASH_TOOL_ALLOWLIST=* to allow all in trusted projects).

mcp-bash doctor
# Expected output includes lines like:
#   ✓ Bash version: 5.x.x (>= 3.2 required)
#   ✓ jq installed: /usr/bin/jq
#   All checks passed! Ready to build MCP servers.

# Preview and apply managed-install repairs (shim + optional upgrade when --min-version is set):
mcp-bash doctor --dry-run
mcp-bash doctor --fix

# Quick end-to-end test (optional):
mcp-bash new demo-server
cd demo-server
mcp-bash run-tool hello --allow-self --args '{"name":"World"}'
# Expected output includes: "Hello, World!"

# Cleanup (the demo-server directory persists until you remove it):
cd .. && rm -rf demo-server

1.6 Uninstall (if needed)

To completely remove mcp-bash from your system:

# 1. Remove the framework installation
rm -rf ~/.local/share/mcp-bash

# 2. Remove the symlink
rm -f ~/.local/bin/mcp-bash

# 3. Remove any generated wrapper scripts (in each project)
rm -f /path/to/your/project/*.sh  # e.g., my-server.sh, my-server-env.sh

# 4. (Optional) Remove PATH addition from your shell config
#    Edit ~/.bashrc or ~/.zshrc and remove the line:
#    export PATH="$HOME/.local/bin:$PATH"

Notes:

• Your project directories (tools/, resources/, prompts/) are untouched—they live in your own repos.
• Wrapper scripts are only created if you ran mcp-bash config --wrapper or --wrapper-env.
• After uninstalling, you can reinstall anytime with the Quick Install command above.

<details> <summary><strong>Something not working?</strong> (click to expand)</summary>

| Symptom | Likely cause | Fix | |---------|--------------|-----| | mcp-bash: command not found | PATH not configured | export PATH="$HOME/.local/bin:$PATH" then open a new shell | | “Operating in minimal mode…” / tools missing | jq/gojq missing | brew install jq or apt install jq | | “blocked by policy” | Default-deny tool policy | CLI: re-run with --allow-self. MCP clients: set MCPBASH_TOOL_ALLOWLIST in client config | | Claude Desktop starts but shows no tools | GUI non-login env / PATH | Use mcp-bash config --wrapper-env and point the client at the wrapper | | macOS Operation not permitted / quarantine | Gatekeeper quarantine | scripts/macos-dequarantine.sh ~/.local/share/mcp-bash (trusted paths only), restart client | | Windows Git Bash path weirdness | MSYS path conversion | MSYS2_ARG_CONV_EXCL="*" (and prefer jq on Windows CI) |

Still stuck? Run mcp-bash doctor (or mcp-bash doctor --json) and include output when opening an issue.

</details>

2. Create Your Project

Your server code lives in a separate project directory:

mcp-bash new my-mcp-server
cd my-mcp-server

Already in a directory you created yourself? Run mcp-bash init --name my-mcp-server [--no-hello] instead.

3. Scaffold Your First Tool

mcp-bash scaffold tool check-disk

This scaffolds tools/check-disk/tool.sh and tools/check-disk/tool.meta.json in your project. You write the logic. Each scaffolded tool also includes tools/check-disk/smoke.sh—run it after edits to ensure your tool’s stdout is valid JSON (update the sample args in the script if you change tool.meta.json).

3.5 (Optional) Add a Test Harness

Create a lightweight runner for tool smoke tests:

mcp-bash scaffold test
./test/run.sh --verbose  # add run_test calls inside test/run.sh

The harness wraps mcp-bash run-tool, validates your project before running, and refuses to overwrite existing test/run.sh or test/README.md.

Security Model (60 seconds)

mcp-bash is secure by default. Here's what that means:

| Layer | Default | What it does | |-------|---------|--------------| | Tool allowlist | Deny all | Tools won't run unless explicitly listed in MCPBASH_TOOL_ALLOWLIST | | Hooks | Disabled | Project hooks (server.d/*.sh) are ignored unless MCPBASH_ALLOW_PROJECT_HOOKS=true | | Tool environment | Minimal | Tools inherit only essential vars (PATH, HOME, TERM). Use MCPBASH_TOOL_ENV_MODE to change |

Quick reference

# Allow a single tool (CLI)
mcp-bash run-tool my-tool --allow-self --args '{}'

# Allow spec