raspi-bash-mcp

An MCP server that exposes a single tool, run_bash, for executing shell commands on a Raspberry Pi (or any host). The tool is implemented as a LangChain @tool and served over the Streamable HTTP transport so any MCP-compatible client can reach it over the network.

Security

run_bash accepts any command and runs it as the user that started the server, with no allowlist and no sandbox. Do not expose this server on an untrusted network. A compromised client can fully take over the host.

Install

Requires Python 3.10+.

pip install -e .

Run

raspi-bash-mcp --host 0.0.0.0 --port 8000
# or
python server.py --host 0.0.0.0 --port 8000

The server listens at http://<host>:<port>/mcp.

Tool

• run_bash(command: str) -> str — executes command via /bin/bash -c and returns stdout (and stderr, if any) inside a fenced code block, followed by the exit code.

Debian package

Build

On any Debian-like host with dpkg-dev and python3:

./scripts/build-deb.sh

The artifact is written to dist/raspi-bash-mcp_<version>_all.deb.

Install on the Raspberry Pi

Copy the .deb to the Pi, then install it. The Pi needs internet access during install so pip can fetch mcp and langchain-core into /opt/raspi-bash-mcp/venv.

# from your workstation
scp dist/raspi-bash-mcp_0.1.0_all.deb pi@raspberrypi.local:~

# on the Pi
sudo apt install ./raspi-bash-mcp_0.1.0_all.deb

apt install ./<file>.deb is preferred over dpkg -i because it resolves dependencies automatically. If you do use dpkg -i and it complains about missing deps, fix them with sudo apt -f install.

Manage the systemd service

The package installs raspi-bash-mcp.service and starts it on install. It is enabled by default, so it also starts at boot.

sudo systemctl status raspi-bash-mcp      # show current state
sudo systemctl start raspi-bash-mcp       # start
sudo systemctl stop raspi-bash-mcp        # stop
sudo systemctl restart raspi-bash-mcp     # restart (e.g. after editing the unit)
sudo systemctl disable raspi-bash-mcp     # do not start at boot
sudo systemctl enable raspi-bash-mcp      # start at boot
journalctl -u raspi-bash-mcp -f           # follow logs

Once running, clients connect to http://<pi-host>:8000/mcp. Verify with:

curl -i http://localhost:8000/mcp         # should return an HTTP response from the MCP server
ss -tlnp | grep 8000                      # confirm it is listening

Change host or port

Edit the ExecStart= line in /lib/systemd/system/raspi-bash-mcp.service (or create a drop-in at /etc/systemd/system/raspi-bash-mcp.service.d/override.conf), then:

sudo systemctl daemon-reload
sudo systemctl restart raspi-bash-mcp

Upgrade and uninstall

sudo apt install ./raspi-bash-mcp_<new-version>_all.deb   # upgrade in place
sudo apt remove raspi-bash-mcp                             # remove binaries + unit
sudo apt purge raspi-bash-mcp                              # also delete /opt/raspi-bash-mcp

Self-hosted apt repository

For installing on multiple machines (or just to get apt update / apt upgrade semantics), publish the .deb as a flat apt repository.

Build the repo

./scripts/build-deb.sh         # produces dist/raspi-bash-mcp_<ver>_all.deb
./scripts/build-apt-repo.sh    # produces dist/apt/{Packages,Packages.gz,Release,*.deb}

The output in dist/apt/ is a self-contained flat repo. Build host needs dpkg-dev and apt-utils.

Serve it

Any static HTTP server works. For a quick local test:

python3 -m http.server --directory dist/apt 8080

For production use, point nginx/Caddy/Apache at dist/apt/, or push the directory to GitHub Pages / S3 / any static host.

Install from the repo (client side)

echo 'deb [trusted=yes] https://slonnik.github.io/mcp/ ./' \
    | sudo tee /etc/apt/sources.list.d/raspi-bash-mcp.list
sudo apt update
sudo apt install raspi-bash-mcp

The trailing ./ is required — it tells apt this is a flat repo (no dists/ layout). [trusted=yes] skips GPG verification because the repo is unsigned; if you need signing, run gpg --clearsign Release after build-apt-repo.sh and distribute the public key to clients via /etc/apt/keyrings/.

Subsequent upgrades are then just:

sudo apt update && sudo apt upgrade raspi-bash-mcp

Automated publish via GitHub Pages

.github/workflows/publish-apt-repo.yml builds the .deb, builds the apt repo, and deploys dist/apt/ to GitHub Pages on every v* tag push (and on manual dispatch). After enabling Pages for the repo (Settings → Pages → "GitHub Actions" as the source), tagging v0.1.0 makes the repo available at https://<owner>.github.io/<repo>/ and clients install with:

echo 'deb [trusted=yes] https://<owner>.github.io/<repo>/ ./' \
    | sudo tee /etc/apt/sources.list.d/raspi-bash-mcp.list
sudo apt update && sudo apt install raspi-bash-mcp