mcp-bash-framework

mcp-bash-framework is a Bash-based MCP (Model Context Protocol) server framework. It enables you to expose your existing Bash scripts and tool scripts as MCP tools without introducing runtime dependencies like Node or Python. The framework provides a registry, runtime, policy, and the standard MCP interactions (lifecycle, prompts, resources, bundles, and more) all implemented in Bash. Use the mcp-bash CLI to scaffold a new server, add tools under server.d/tools, and package them into a distributable bundle. The tooling includes features for concurrency, timeouts, cancellation, and a structured prompt/response system that integrates with MCP clients like Claude Desktop or Cursor. You’ll primarily work by writing your own tool scripts inside a project directory and letting mcp-bash expose them to MCP clients via the framework.

Typical workflow: install the framework, create a new server project with mcp-bash new my-server, implement tools under tools/, define server.d/server.meta.json, and then use mcp-bash run-tool or mcp-bash bundle to test and package. The client-side experience remains consistent with other MCP servers: you call list, call, and prompt definitions through the standard MCP protocol, while the server side runs as Bash scripts within the project. This approach keeps dependencies minimal and makes it easy to audit, inspect, and modify your server logic directly in Bash.

Prerequisites

• Bash 3.2+ (macOS/Linux stock) and a POSIX-compliant shell
• Optional: jq or gojq for full functionality (tools/resources/prompts)
• curl or git for installation

Install from Quick Install Script (recommended for local dev)

1. Quick install (trusted networks):

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

2. Verified install (production/security):

version="v1.1.3"
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 -
# 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}"

3. Manual/offline install (offline 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

4. Verify works

mcp-bash doctor

Note: The framework is designed to be added to an existing Bash project. After installing, you typically scaffold a new server project with mcp-bash new my-server, define your tools under tools/, and use mcp-bash run-tool, mcp-bash bundle, etc., to test and package your MCP server.

Tips and common issues:

• This framework runs entirely in Bash; ensure your tools are portable POSIX shell scripts when possible.
• Use mcp-bash doctor to verify your environment and prerequisites (Bash version, jq/gojq availability).
• Environment variables like MCPBASH_ALLOW_PROJECT_HOOKS and MCPBASH_TOOL_ALLOWLIST control security and tool exposure in trusted projects. Set them as needed for your environment.
• When packaging, the bundle will include your server.d, tools/, prompts, resources, and any assets defined in your project metadata.
• If you encounter issues around concurrency or timeouts, review your tool scripts for blocking operations and consider implementing proper backgrounded tasks or progress reporting within the MCP framework.
• The README indicates this is a pure Bash implementation with stdio-based MCP transport; HTTP/SSE options exist via Remote Connectivity documentation if you ever expose your server beyond stdio.