A framework for building MCP servers using pure Bash scripts.
mcp-bash
Repository: `mcp-bash-framework` • CLI/Binary:
mcp-bash
Contents
- MCP Spec Coverage
- Why Bash?
- Quick Start
- Security Model (60 seconds)
- Configure Your MCP Client
- MCPB Bundles
- 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(Claude Desktop / Cursor / Windsurf)"]
Transport["stdio (JSON-RPC)"]
Framework["mcp-bash framework(registry + runtime + policy)"]
Project["Your projecttools/ 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).
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 | curl | bash or git clone |
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 tempo
Environment Variables
MCPBASH_REMOTE_TOKENShared-secret guard for remote connectivityConfiguration
{
"mcpServers": {
"mcp-bash": {
"command": "/path/to/mcp-bash",
"args": ["start"],
"env": {
"PATH": "/usr/local/bin:/usr/bin:/bin"
}
}
}
}