OpenSSF Scorecard

$_mcbox

mcbox is a pluggable MCP (Model Context Protocol) server written in Bash and jq, fully tested using Bats, shellcheck and shfmt. It aims to be lightweight, portable, and just good enough for AI agents that use local tool execution through stdio transport.

The project has a few non-goals:

• No concurrency/parallel processing
• No support for high throughput
• No streaming responses
• No MCP transports other than stdio

Aside from that, it's a great way to provide your own tools for local AI agents, and write those tools in any programming language you like.

Check out the documentation to get started.

Support

Feel free to open a GitHub issue to ask for help, file a bug report, or request a new feature.

Development

Check out the Contributing guide and the Development documentation for how to get started with development.

Prerequisites

You'll need bash and jq installed to run the MCP server. Both can be installed using your preferred package manager (e.g. Homebrew).

brew install bash
brew install jq

For development, you'll also need to install:

• Node.js (LTS version) and the NPM CLI (which already comes with Node); we recommend using fnm, the "Fast Node Manager", to install Node's current LTS version. Follow the instructions in fnm's GitHub repo to install it.
• shellcheck: follow the instructions to install using your preferred package manager
• shfmt: use your preferred package manager (see options listed in its GitHub README)

We recommend using EditorConfig for automated code formatting. Install the EditorConfig extension for your favorite IDE.

Code formatting and linting

To run the shfmt format and shellcheck linting checks, use:

./test/shfmt.bash
./test/shellcheck.bash

To fix formatting you can run:

WRITE=true ./test/shfmt.bash

Tests

Test files in this project are located under the test/ directory, and named with a .test.bats extension, by convention.

The Bats testing framework and helpers are included in this repo as git submodules under the test/ directory.

Unit test files are named as <function_name>.test.bats.

To run all tests:

./test/test.bash

To run a specific test file:

./test/bats/bin/bats <function_name>.test.bats

The npx command from Node's NPM is used for end-to-end testing. You must have Node.js (LTS) installed to run the E2E tests.

Running the smoke test server

A pre-configured "smoke test" server can be run with:

./test/helpers/smoketest-server/mcbox.bash

The MCP Inspector tool can be used to visually inspect the smoke test server, with:

npx @modelcontextprotocol/inspector ./test/helpers/smoketest-server/mcbox.bash

The smoke test server is used in end-to-end tests:

./test/bats/bin/bats ./test/e2e.test.bats

Built with

• bash
• jq
• Bats
• shellcheck
• shfmt
• mcp-cli
• MCP Inspector

Acknowledgements

Thanks to @flimzy for initial discussions about this project, when it was still being written in Go.

Inspiration for rewriting it in Bash came after reading these two blog posts:

Muthukumaran Navaneethakrishnan, "Why I Built an MCP Server Sdk in Shell (Yes, Bash)":

• https://medium.com/@muthuishere/why-i-built-an-mcp-server-sdk-in-shell-yes-bash-6f2192072279 (2025-05-29)
• https://github.com/muthuishere/mcp-server-bash-sdk

Anton Umnikov, "Minimalistic MCP Server in bash script":

• https://dev.to/antonum/minimalistic-mcp-server-in-bash-script-10k5 (2025-05-31)
• https://github.com/antonum/mcp-server-bash

Authors

Andre Silva - @andreswebs

License

This project is licensed under the GPL-3.0-or-later.