← Back to pi-bay

Pi Bay

Platform: Cross-Platform Version 0.9.40 Node 20+ Protocol: MCP Tools: 13 License: MIT Status: Beta

pi-bay is an App and MCP Server for managing Raspberry Pis and other SSH devices on a LAN: find them, browse and edit their files, and run commands in an SSH terminal.

Quick start

Requires Node.js 20 or newer and SSH enabled on the target device.

npx pi-bay

Your browser will open automatically! If it doesn't, head to http://localhost:8383.

Devices

Files

Run and terminal

MCP server

pi-bay includes a dependency-free Model Context Protocol server, enabled by default on Raspberry Pi hosts. On macOS and other non-Pi hosts, enable MCP in the user interface or with --mcp-stdio or --mcp-http.

Agent configuration

In Claude Desktop, open Settings → Developer → Edit Config to get to the configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or the equivalent file on Windows or Linux), and add the server under mcpServers. --mcp-stdio is optional here: pi-bay detects an MCP client on stdin and starts stdio on its own.

{
  "mcpServers": {
    "pi-bay": {
      "command": "npx",
      "args": ["-y", "pi-bay", "--mcp-stdio"]
    }
  }
}

Cursor takes the same JSON, here and under Streamable HTTP. Put it in ~/.cursor/mcp.json, or in .cursor/mcp.json inside a project.

Streamable HTTP

Use HTTP when the MCP client runs on another computer or Raspberry Pi:

npx pi-bay --mcp-http

The normal web interface remains available and MCP is served at http://HOST:8383/mcp. Configure the MCP agent to connect over HTTP, replacing PI_HOST_ADDR with the platform running pi-bay:

{
  "mcpServers": {
    "pi-bay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://PI_HOST_ADDR:8383/mcp", "--allow-http"]
    }
  }
}

--allow-http permits the connection over a trusted local network. On macOS and other non-Pi hosts, add --host 0.0.0.0 when starting pi-bay to make it reachable from another computer. A Raspberry Pi listens on the LAN by default.

No authentication or TLS: MCP tools can run shell commands, overwrite and delete files, install software, and reboot devices. HTTP mode is intended only for a trusted local network. Do not expose /mcp or pi-bay’s port directly to the internet.

The server supports MCP revision 2026-07-28 and the legacy initialize flow through 2025-03-26. It uses plain JSON responses rather than SSE because it does not send server-initiated messages.

Signing in

pi_device_authenticate is the only tool that takes a username and password. The other tools reuse its connection, or sign in again by themselves with:

  1. The keychain: a password saved with save_password: true (or Save password in the app) in macOS Keychain or Linux Secret Service.
  2. SSH keys: the SSH agent (SSH_AUTH_SOCK) and the default identity files (~/.ssh/id_ed25519, ~/.ssh/id_rsa).

When neither works, the tool asks the agent to call pi_device_authenticate first.

MCP tools

Tool Purpose
pi_devices_list List discovered devices on the LAN with model, ctrlPi status, and saved credential availability.
pi_device_info Get hardware model, OS, kernel, storage, memory, uptime, and ctrlPi details.
pi_device_authenticate Sign in over SSH and optionally save the password to the system keychain.
pi_command_run Run a shell command and return its output and exit code, with a timeout (default 30 s, max 5 min).
pi_files_list List one folder relative to $HOME, optionally with hidden files.
pi_file_read Read a file as UTF-8 text or base64.
pi_file_write Create or overwrite a UTF-8 or base64 file, up to 16 MB, creating missing parent folders.
pi_directory_create Create a folder relative to $HOME.
pi_path_rename Rename or move a file or folder relative to $HOME.
pi_path_delete Permanently delete a file or recursively delete a folder relative to $HOME.
pi_device_reboot Reboot the device.
pi_ctrlpi_install Install or update the ctrlPi API (pi-gpio-api), and start its service when sudo needs no password.
pi_ui Open the web UI in the browser, or return its address when pi-bay runs on another computer. action: "stop" stops it.

Call pi_devices_list first, then pass its device_id to device-specific tools.

Installing the ctrlPi API

Install ctrlPi API in the top-right menu installs pi-gpio-api on the connected Pi. A popup asks for the agent name, the API key, and the Lite (recommended) or Full package. The API key is optional: left empty, it is the default your-secret-key, which is public, so change it before relying on the agent. pi-bay writes ~/pi-gpio-api/config.json with the name and key, then runs the installer in the Terminal tab so you can follow it.

If the Pi already has ~/pi-gpio-api/config.json, its agent name and API key are kept and the installer updates pi-gpio-api in place. The installer ends with the sudo commands that create and start the pi-gpio-api service, or restart it; run them in the same terminal.

The pi_ctrlpi_install MCP tool does the same without the terminal. On a first install a missing name or key gets the installer's defaults, the hostname and your-secret-key, and the result warns about the default key. On a Raspberry Pi where sudo needs no password it then creates and starts, or restarts, the service itself; otherwise it returns the installer's output with the commands to run.

Toggling USB power

Toggle Pi USB Power in the top-right menu turns off every USB port on the connected Pi that supports power switching, then turns them back on after 3 seconds, using uhubctl. A popup explains what will happen and, when uhubctl is missing, that it is installed first with apt. The commands run in the Terminal tab, where sudo can ask for your password. It is refused on a Pi that boots from a USB drive, since cutting its USB power would crash it.

Working with files

Drag and drop

Requirements

Install

From GitHub:

git clone https://github.com/ctrlpi/pi-bay.git
cd pi-bay
npm start

Or install the npm package locally:

npm install pi-bay
npx pi-bay

Options

pi-bay [--port PORT] [--host ADDRESS] [--allow-host NAME] [--ssh-port PORT] [--api-port PORT] [--api-key KEY] [--no-open] [--mcp-stdio | --mcp-http | --no-mcp] [--help] [--version]
Option Environment Default Purpose
--port PORT 8383 Web server port. When the default is busy on a desktop, one of the next 3 is used.
--host PI_BAY_HOST Automatic 127.0.0.1 normally; 0.0.0.0 on a Raspberry Pi host.
--allow-host PI_BAY_ALLOW_HOSTS - Extra host name to accept, such as pi4.lan. Repeat the flag, or separate names with commas. IP addresses, localhost and the machine's own name always work.
--ssh-port PI_BAY_SSH_PORT 22 SSH port checked during discovery and used for connections.
--api-port PI_BAY_API_PORT 8314 ctrlPi API port.
--api-key PI_BAY_API_KEY your-secret-key API key used for /config/read.
--no-open PI_BAY_NO_OPEN false Do not automatically open the default browser on start. Browsers are never opened automatically on Raspberry Pi hosts.
--mcp-stdio PI_BAY_MCP_STDIO false Run only the MCP stdio transport. Optional when an MCP client starts pi-bay: it is detected automatically.
--mcp-http PI_BAY_MCP_HTTP Pi only Add Streamable HTTP MCP at /mcp to the normal web server. Enabled automatically on Raspberry Pi hosts.
--no-mcp PI_BAY_NO_MCP false Disable all MCP transports, including the Raspberry Pi HTTP default.
--help - - Show command-line help.
--version - - Show the installed version.

No environment variables are required: each one in the table is an optional alternative to its flag. Command-line values take precedence over environment variables. Boolean environment variables accept true or false, and 1 or 0.

Running on a Raspberry Pi

On Linux, pi-bay checks /proc/device-tree/model. When the host is a Raspberry Pi, it listens on 0.0.0.0 by default so another computer on the same network can open it. It does not try to launch a browser on the Pi itself, and Streamable HTTP MCP is enabled at /mcp by default. Start with --no-mcp to disable MCP while keeping the web interface available, or switch MCP off from the top-right menu while it runs.

Only expose pi-bay on a trusted network. It has no login of its own and can run commands on, and change files of, every device it has signed in to.

How discovery works

Saved information

~/.ctrlpi/pi-bay-devices.json stores device identity, username, model, and whether a saved password exists. It is written with mode 0600 and lives outside the app folder, so reinstalling or upgrading pi-bay keeps it.

Passwords are not written to this file. They are stored in macOS Keychain or Linux Secret Service, and with a saved password Connect works with the password field left empty. A password used without Save password stays in memory for the current session only.

Backups

Download as ZIP creates a standard archive of the home folder. Restore from ZIP extracts an archive into the home folder, overwrites matching paths, and leaves other files untouched. Keep a separate copy of important files before restoring.

Security

pi-bay can run commands, overwrite and delete files, install software, and reboot devices. It is intended for a trusted local workstation and LAN.

Do not expose it to an untrusted network, and connect only to devices you trust.

Troubleshooting

No device appears

Login fails

Upload, move, or restore fails

The SSH user needs write permission for the target folder. Files outside $HOME cannot be changed from pi-bay's file browser; use the Terminal tab with sudo instead.

The ctrlPi agent does not start after installing

The installer only prints the sudo commands for the pi-gpio-api service. Run them in the Terminal tab. pi_ctrlpi_install runs them itself only when sudo needs no password, and reports needs_sudo otherwise.

Tests

Run the test suite with:

npm test

The test suite covers parsing, device discovery, HTTP and MCP APIs (MCP over stdio and HTTP), DNS-rebinding and cross-origin protection, sign-in checks, path safety, text and binary detection, the MCP tools' argument checks, and ZIP handling and restore. It needs no device on the network.

Known limits

Related projects

License

MIT