What are the requirements for mcp-bash?

mcp-bash requires the following environment variables: MCPBASH_REMOTE_TOKEN (optional). You'll also need a compatible MCP client like Claude Desktop or Claude Code.

Is mcp-bash free to use?

Yes, mcp-bash is open source and free to use. You can find the source code on GitHub.

What MCP clients support mcp-bash?

mcp-bash works with any MCP-compatible client including Claude Desktop (Anthropic's official desktop app), Claude Code (CLI tool), Cursor, and other editors with MCP support.

How do I configure mcp-bash?

Configure mcp-bash by adding it to your MCP client's config file. The setup block at the top of this page generates a ready-to-paste config for Claude Code, Cursor, Codex, Windsurf, and Claude Desktop.

MCP server/ai-tools

mcp-bash MCP Server

Q: How do I install mcp-bash?

Install mcp-bash by running: git clone https://github.com/yaniv-golan/mcp-bash-framework && cd mcp-bash-framework && ./install.sh

The most complete MCP implementation in pure Bash.

★ 5 yaniv-golan/mcp-bash-framework ↗by yaniv-golanupdated Apr 9, 2026

Manual setup required. The maintainer's config contains paths only you know - edit the placeholders below before adding it to Claude Code.

Prepare the server locally

Run this once before adding it to Claude Code.

git clone https://github.com/yaniv-golan/mcp-bash-framework
cd mcp-bash-framework
./install.sh

Register it in Claude Code

claude mcp add mcp-bash -- mcp-bash run /path/to/your/project

Replace any placeholder paths in the command with the real path on your machine.

Make your agent remember this setup

mcp-bash's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.

npx conare@latest

Free · one command · indexes the sessions already on disk. Set up in the browser instead →

What it does

Full MCP specification coverage including tools, resources, and prompts
Runs on Bash 3.2+ with no Node.js or Python dependencies
Handles concurrency, timeouts, and cancellation natively
Supports project scaffolding and bundling for distribution
Compatible with macOS, Linux, and Windows environments

Environment Variables

MCPBASH_REMOTE_TOKENShared-secret token for remote connectivity

Try it

→Create a new MCP server project using mcp-bash.

→Scaffold a new tool for my existing mcp-bash project.

→Bundle my current mcp-bash project into a distributable package.

→Check the health status of my mcp-bash server.

Original README from yaniv-golan/mcp-bash-framework

mcp-bash

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

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

→ 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	`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

Frequently Asked Questions

What are the key features of mcp-bash?

Full MCP specification coverage including tools, resources, and prompts. Runs on Bash 3.2+ with no Node.js or Python dependencies. Handles concurrency, timeouts, and cancellation natively. Supports project scaffolding and bundling for distribution. Compatible with macOS, Linux, and Windows environments.

What can I use mcp-bash for?

Exposing existing shell scripts as AI-accessible tools. Building MCP servers in air-gapped or minimal environments. Creating lightweight AI integrations without heavy runtime overhead. Automating system tasks directly from an AI assistant.

How do I install mcp-bash?

Install mcp-bash by running: git clone https://github.com/yaniv-golan/mcp-bash-framework && cd mcp-bash-framework && ./install.sh

What MCP clients work with mcp-bash?

mcp-bash works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Conare · memory for coding agents

Turn this server into reusable context

Keep mcp-bash docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Set up free$npx conare@latest