muthuishere/mcp-server-bash-sdk

📦 What is mcp‑server‑bash‑sdk?

A tiny, zero‑overhead implementation of the Model Context Protocol (MCP) 2026‑07‑28 written entirely in Bash. It lets you expose tool functions (e.g., get_weather, list_files) to an AI‑agent client via the same JSON‑RPC‑style request/response format that larger MCP servers use, but without pulling in a heavyweight runtime like Node or Python.

---

🎯 Core idea

• Stateless, per‑request protocol – the 2026‑07‑28 revision removed handshakes and sessions, so each request is a single JSON line that can be processed in a simple read‑loop.
• One code base, two transports – the same Bash script can serve requests over stdio (the typical way an LLM‑agent spawns a subprocess) or over a local HTTP POST endpoint using socat/netcat.
• Tool discovery via naming – any Bash function whose name starts with tool_ is automatically listed in the server/discover response and can be invoked with tools/call.

---

🛠️ Main components (as described in the README)

File / Directory	Role
mcpserver_core.sh	Handles JSON‑RPC framing, MCP method dispatch, version negotiation, and validates output against the official JSON Schema (via jq and optionally jsonschema).
mcpserver_http.sh	Thin wrapper that turns the core into a Streamable HTTP listener (POST‑only, loopback only).
moviemcpserver.sh (and other examples)	Concrete server scripts that source the core and then define tool_* functions containing the business logic.
assets/	JSON files that describe the server (discover payload) and the list of tools (tools payload).
spec/	Vendored MCP schema used by the conformance test suite.
docs/adr/ & docs/spikes/	Design rationale (Architecture Decision Records) and experimental scripts that proved certain Bash behaviours on macOS, Debian, Alpine, etc.
examples/	Four ready‑to‑run server demos (movie catalog, git wrapper, weather API, file server) plus a step‑by‑step “build‑your‑own” guide.
test_*.sh & scripts/test-linux.sh	Unit‑ and integration‑tests covering the core logic, discovery shape, schema conformance, and both transports on multiple Linux flavours.

---

🚀 Getting started (quick‑start flow)

1. Clone & make executable

   git clone https://github.com/muthuishere/mcp-server-bash-sdk
   cd mcp-server-bash-sdk
   chmod +x mcpserver_core.sh moviemcpserver.sh
   

2. Run a request via stdio

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

3. Run as a local HTTP endpoint

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

4. Run the test suite (requires jq; optional python+jsonschema for schema test)

   ./test_mcpserver_core.sh          # 31 unit tests
   ./test_http_transport.sh          # 19 HTTP tests
   ./scripts/test-linux.sh all       # verifies on Debian, Ubuntu, Alpine via Docker
   

---

🧩 How to build your MCP server in Bash

1. Create a wrapper script (e.g., weatherserver.sh).
2. Set configuration paths (MCP_CONFIG_FILE, MCP_TOOLS_LIST_FILE, MCP_LOG_FILE) before sourcing mcpserver_core.sh.
3. Define tool_* functions – each receives a single JSON string argument, must echo the result on success, and return 0. On error, echo an explanatory message and return 1; the core will translate this into a JSON response with isError: true (still a successful HTTP/stdio round‑trip).
4. Choose a transport – run the script with no args for stdio, or with --http (and optionally MCP_HTTP_PORT, MCP_HTTP_BIND, MCP_ALLOWED_ORIGINS).
5. Add the server to an MCP client config – e.g., in an LLM‑assistant’s mcp.servers JSON, point type to stdio and command to your script.

---

📌 Limitations (as listed by the authors)

• Local‑only HTTP – no TLS, no authentication; exposing it publicly requires a reverse proxy.
• No SSE / streaming responses – the 2026‑07‑28 spec removed session‑based streams, so progress notifications aren’t supported.
• Single‑client stdio – one process handles one client at a time (≈30 req/s).
• Feature gaps – no resources, prompts, MRTR input, or the “tasks” extension.
• Version lock – only the 2026‑07‑28 revision is implemented; older MCP versions are rejected.

---

📚 Documentation & community

• Full docs site – https://muthuishere.github.io/mcp-server-bash-sdk/
• Architecture Decision Records – docs/adr/ explains why the SDK is shaped the way it is.\n* Discord community – AgentNexus (https://discord.gg/V9C2kvHC8D) hosts a channel #mcp-bash-sdk for questions and showcases.
• Author – maintained by deemwar (https://examples.deemwar.com); contact io@deemwar.com for production help.

---

✅ TL;DR

If you need a lightweight, Bash‑only MCP server to expose simple tools to an AI‑agent (e.g., for prototyping, local development, or environments where installing Node/Python is undesirable), this repository gives you a ready‑made, spec‑compliant implementation with both stdio and local‑HTTP bindings, thorough tests, and clear guidance on adding your own tool functions.