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