🐚 MCP Server in Bash

A lightweight, zero-overhead implementation of the Model Context Protocol (MCP) server in pure Bash — targeting the current 2026-07-28 revision.

📖 Documentation site · 🧩 Examples · 🧠 Architecture decisions · 🔬 Spikes

Why? Most MCP servers are just API wrappers with schema conversion. This implementation provides a zero-overhead alternative to Node.js, Python, or other heavy runtimes.

Why now? The 2026-07-28 revision made MCP stateless: no initialize handshake, no sessions, no server-initiated requests. One line in, one line out — which is exactly the shape of a shell read loop. Bash went from an awkward fit to a natural one.

---

📋 Features

• ✅ MCP 2026-07-28 — stateless, per-request version negotiation
• ✅ Both standard transports: stdio and Streamable HTTP, from the same server file
• ✅ server/discover, tools/list, tools/call
• ✅ Dynamic tool discovery via function naming convention
• ✅ External configuration via JSON files
• ✅ Output validated against the official published JSON Schema

---

🔧 Requirements

• Bash 3.2 or newer (3.2 is what macOS ships as /bin/bash)
• jq for JSON processing (brew install jq / apt install jq / apk add jq)
• (HTTP transport only) socat preferred, or netcat — see the note under Transports
• (optional) Python with jsonschema, only to run the schema conformance test

Supported platforms

Verified by running the real test suites on each, not by inspection — ./scripts/test-linux.sh all reproduces the Linux rows on any machine with Docker.

Platform	Shell	Unit	HTTP
macOS	bash 3.2 (/bin/bash) and 5.x	31/31	19/19
Debian / Ubuntu	bash 5.2	31/31	19/19
Alpine (musl + busybox)	bash 5.3	31/31	19/19

Docker is needed only to verify other platforms — never to run a server.

---

🚀 Quick Start

1. Clone the repo

git clone https://github.com/muthuishere/mcp-server-bash-sdk
cd mcp-server-bash-sdk

2. Make scripts executable

chmod +x mcpserver_core.sh moviemcpserver.sh

3. Try it out — every request carries its protocol version in params._meta:

echo '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' | ./moviemcpserver.sh

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_movies","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' | ./moviemcpserver.sh

4. Or run it as a local HTTP endpoint

./moviemcpserver.sh --http        # http://127.0.0.1:3000/mcp

5. Run the tests

./test_mcpserver_core.sh                          # 31 unit tests
./test_mcpserver_core.sh test_discover_shape      # a single test
./test_conformance.sh                             # validate against the official schema
./test_http_transport.sh                          # 19 HTTP transport tests
./scripts/test-linux.sh all                       # run everything on Debian, Alpine and Ubuntu

---

🏗️ Architecture