Permet à un client IA de gérer des Raspberry Pis et des appareils SSH sur un réseau local en parcourant les fichiers, en exécutant des commandes shell et en contrôlant le matériel.
Aussi connu sous ctrlpi/pi-bay, @ctrlpi/pi-bay
- Étoiles
- 1
- Outils
- 12
- Téléchargements, 30 jours
- 539
- Dernière version
- 0.9.34
- Dernier commit
- 6 nov. 2026
- Licence
- MIT
Qu'est-ce que pi-bay MCP ?
Permet à un client IA de gérer des Raspberry Pis et des appareils SSH sur un réseau local en parcourant les fichiers, en exécutant des commandes shell et en contrôlant le matériel. Il expose 12 outils, comme pi_devices_list, pi_device_info, pi_device_authenticate.
Résumé généré à partir du README du projet
À propos du MCP server pi-bay
Pi Bay offre un moyen de gérer des Raspberry Pis et d'autres appareils compatibles SSH sur un réseau local. Il fonctionne à la fois comme une application web et comme un MCP server, permettant aux utilisateurs de découvrir du matériel, de parcourir des systèmes de fichiers via SFTP et d'exécuter des commandes shell. Le système est conçu pour les développeurs et les passionnés qui ont besoin d'interagir avec du matériel distant via un client IA ou une interface web.
Les utilisateurs peuvent installer le serveur localement en utilisant Node.js 20 ou une version supérieure. Pour l'intégration IA, il prend en charge stdio pour les clients locaux comme Claude Desktop et Cursor, ou le streamable HTTP pour les connexions à distance. Le serveur gère l'authentification en utilisant les trousseaux de clés du système ou les clés SSH. Il inclut des outils spécifiques pour la gestion du matériel, tels que le redémarrage d'appareils, la gestion de l'alimentation USB via uhubctl et l'installation de pi-gpio-api pour le contrôle matériel.
Ce que vous pouvez faire avec
- 1Découvrir le matériel localUn client IA peut scanner le réseau local pour trouver les Raspberry Pis disponibles et identifier leurs modèles spécifiques ainsi que leurs adresses IP.
- 2Gérer des fichiers à distanceUn développeur peut ordonner à un agent de créer, renommer ou supprimer des fichiers et des dossiers dans le répertoire personnel d'un appareil distant.
- 3Contrôler les services matérielsLe serveur peut être utilisé pour installer ou mettre à jour l'API nécessaire au contrôle GPIO sur un Pi connecté.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer pi-bay MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller pi-bay MCP dans Claude Code
$ claude mcp add pi-bay -- npx -y @ctrlpi/pi-bayInstaller pi-bay MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pi-bay": {
"command": "npx",
"args": [
"-y",
"@ctrlpi/pi-bay"
]
}
}
}Installer pi-bay MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"pi-bay": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ctrlpi/pi-bay"
]
}
}
}Installer pi-bay MCP dans VS Code CLI
$ code --add-mcp '{"name":"pi-bay","type":"stdio","command":"npx","args":["-y","@ctrlpi/pi-bay"]}'Installer pi-bay MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"pi-bay": {
"command": "npx",
"args": [
"-y",
"@ctrlpi/pi-bay"
]
}
}
}Installer pi-bay MCP dans Codex
$ codex mcp add pi-bay -- npx -y @ctrlpi/pi-bayInstaller pi-bay MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.pi-bay] command = "npx" args = ["-y", "@ctrlpi/pi-bay"]
Installer pi-bay MCP dans Gemini CLI
$ gemini mcp add -s user pi-bay npx -- -y @ctrlpi/pi-bayInstaller pi-bay MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pi-bay": {
"command": "npx",
"args": [
"-y",
"@ctrlpi/pi-bay"
]
}
}
}Outils MCP pi-bay 12
Détectés depuis le READMEpi_devices_listpi_device_infopi_device_authenticatepi_command_runpi_files_listpi_file_readpi_file_writepi_directory_createpi_path_renamepi_path_deletepi_device_rebootpi_ctrlpi_install
| pi_devices_list | — | |
| pi_device_info | — | |
| pi_device_authenticate | — | |
| pi_command_run | — | |
| pi_files_list | — | |
| pi_file_read | — | |
| pi_file_write | — | |
| pi_directory_create | — | |
| pi_path_rename | — | |
| pi_path_delete | — | |
| pi_device_reboot | — | |
| pi_ctrlpi_install | — |
Vérifications automatisées
Exécuté le 13 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessiblectrlpi/pi-bay is public and reachablegithub.com/ctrlpi/pi-bay ↗Réussi
- Le nom du package correspond au dépôt source@ctrlpi/pi-bay names ctrlpi/pi-bay as sourcenpmjs.com/package/@ctrlpi/pi-bay ↗Réussi
- Provenance du build (attestation Sigstore)No build attestation published for this releaseNon vérifié
- Licence open source (OSI)MITspdx.org/licenses/MIT.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-11-08github.com/ctrlpi/pi-bay ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNo popular package one edit away from @ctrlpi/pi-bayRéussi
- Aucun avis critique dans le package ou ses dépendances11 resolved dependencies checked; no critical advisoryosv.dev ↗Réussi
- Aucune instruction cachée destinée au modèle12 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNo tool named like delete, drop or execRéussi
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubPi Bay
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 @ctrlpi/pi-bay
Your browser will open automatically! If it doesn't, head to http://localhost:8383.
Devices
- Finds Raspberry Pis and other SSH devices on the local network as the scan runs.
- Detects ctrlPi agents, including Picos and ESP32s.
- Shows each device's name, IP and MAC address, model, and ctrlPi version.
- Signs in over SSH and saves passwords in the system keychain.
- Disconnects, toggles a Pi's USB power, and reboots it from the menu.
Files
- Browses the home folder over SFTP as a searchable, collapsible tree, with hidden files optional.
- Lists a selected folder's files with their sizes and modification dates.
- Creates, renames, moves, uploads, downloads, and recursively deletes files and folders.
- Opens text files, edits them in the browser, and formats JSON.
- Renders a Markdown preview.
- Detects binary files and offers them for download instead of displaying them as text.
- Uploads files and whole folders by drag and drop.
- Downloads and restores the home folder as a standard ZIP archive.
- Installs or updates the ctrlPi API (pi-gpio-api) on a Raspberry Pi.
Run and terminal
- Runs
.py,.sh,.bash, and.jsfiles on the device from their own folder. - Opens an interactive SSH shell in full color.
- Keeps the session open while you switch to Files and back.
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 enabling stdio:
{
"mcpServers": {
"pi-bay": {
"command": "npx",
"args": ["-y", "@ctrlpi/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 @ctrlpi/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
/mcpor 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:
- The keychain: a password saved with
save_password: true(or Save password in the app) in macOS Keychain or Linux Secret Service. - 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. |
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. 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
- After login, opens the home folder's only folder with its first entry selected, or selects the home folder when it has several folders or none.
- Selecting a folder lists its files on the right with name, size and modification date; click any row to open that file or folder. The toolbar then offers Rename and Delete for the folder.
- Edit (or a double-click on the open file) switches to the editor, which shows only Format JSON (for
.jsonfiles), Cancel and Save. Format JSON reformats with 3-space indentation. - Run runs the open
.py,.sh,.bash, or.jsfile in the Terminal tab from the file's own folder:python3 file.py,./file.sh, ornode file.js. - Move to folder… in the file toolbar moves the open file to any folder already shown in the tree.
- New file…, New folder…, Upload files… and Upload folder… work in the selected folder (or the open file's folder). pi-bay asks before overwriting files it already shows.
- Deleting the open file selects the folder it was in. File and folder rows in the tree have a delete button.
- The browser tab names the open file or selected folder.
Drag and drop
- Drop files or whole folders from your computer onto the file tree to upload them. Dropped on a folder row, they go into that folder; dropped on a file row, into that file's folder; anywhere else, into
$HOME. Folder structure is kept and missing folders are created. - Drop files onto a selected folder's listing on the right to upload them into that folder.
- Drop a file onto an open text file to put its text in the editor; nothing is written until Save.
- Drag a file or folder onto another folder to move it there, or onto an empty part of the tree to move it to
$HOME. - Drag a file out of the window onto your desktop to download it (Chrome and Edge).
Requirements
- Node.js 20 or newer.
- macOS or Linux.
- SSH enabled on each device, on a trusted local network that permits discovery and SSH access.
- For saved passwords on Linux,
secret-tool(Secret Service).
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 @ctrlpi/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]
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
- The scan covers the
/24network of the address the computer uses to reach other networks (offline, its first active IPv4 interface) and checks SSH on port 22 (--ssh-port) and a ctrlPi agent's/helloon port 8314 (--api-port). - Names come from ctrlPi, reverse DNS, and on macOS from Bonjour and SMB/NetBIOS.
- A device is verified as a Raspberry Pi by its MAC vendor or a
raspberrypihostname. A ctrlPi agent without SSH is shown as an ESP32 when its model or name says so, and as a Pico otherwise. Other SSH hosts are marked unverified. - For a ctrlPi agent, pi-bay reads
/config/readwith the configured API key: the model (agent.platform), operating system (agent.os) and version (agent.version). Live scan information is preferred; a previously saved model is used when the device does not return one. After SSH login, pi-bay also reads the Raspberry Pi model from Linux and saves it for future scans.
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.
- The server listens on
127.0.0.1by default, or0.0.0.0when the host is a Raspberry Pi. - Requests must be addressed to an IP address,
localhost, the machine's own name (or<name>.local), or a name given with--allow-host. Any other name gets403, which blocks DNS rebinding: a web page cannot point its own domain at your machine and drive pi-bay through it. The terminal's WebSocket is checked the same way. - State-changing requests require same-origin access.
- Remote file paths are restricted to the authenticated user's home directory and traversal paths are rejected.
- SSH host keys are accepted automatically without interactive verification.
- The app has no authentication, TLS, authorization, or multi-user isolation.
Do not expose it to an untrusted network, and connect only to devices you trust.
Troubleshooting
No device appears
- pi-bay scans only the
/24network of the address the computer uses to reach other networks. Devices on another subnet or VLAN are not found; with a VPN that routes all traffic, the VPN's address is used, so disconnect it to scan the local network. - Check that SSH is enabled on the Pi (
sudo raspi-config→ Interface Options → SSH) and listening on port 22, or start pi-bay with--ssh-port. - Click the scan button again after a Pi has finished booting.
Login fails
- The default username is
pi; current Raspberry Pi OS images use the username chosen when the card was written. - A saved password that no longer works is replaced the next time you log in with Save password selected.
- An MCP tool that says to sign in needs
pi_device_authenticatefirst, or a saved password.
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
- ZIP download: up to 500 files and 100 MB, skipping files over 20 MB.
- ZIP restore: up to 64 MB, 4096 files, and 256 MB unpacked.
- Dragging a file out to download it works in Chromium-based browsers only.
- Saved passwords are not supported on Windows.
Related projects
pi-gpio-api: Raspberry Pi GPIO REST server that reads inputs and drives outputs (and named sensors) over an HTTP API.pico-gpio-api: Raspberry Pi Pico W port of the GPIO REST server, with the same endpoints, wire format, and auth.esp32-gpio-api: ESP32 port of the GPIO REST server for MicroPython, with the same endpoints, wire format, and auth.mcp-bridge: MCP server that exposes GPIO control as tools for AI agents (e.g. Claude), executing them over the agents' REST API.homebridge-ctrlpi: A Homebridge plugin that brings Raspberry Pi, Pico W, and ESP32 GPIO into Apple Home, by driving one or more GPIO agents over their REST API.matter-bridge(coming soon): Matter bridge that exposes GPIO pins and sensors to any Matter platform (Apple Home, Google Home, Alexa, Home Assistant), driven over the agents' REST API.ctrlpi-cli: Command-line interface for interacting with ctrlPi agents, with shared agent configuration.ctrlpi-lab: A local browser dashboard for your ctrlPi setup. Test GPIO and sensor endpoints, watch webhook events, and tail agent logs.pico-bay: An app and MCP server for managing Raspberry Pi Pico and ESP32 boards with MicroPython or CircuitPython over USB.
License
Questions sur pi-bay MCP
Comment ajouter pi-bay MCP à Claude Code ?
Exécutez claude mcp add pi-bay -- npx -y @ctrlpi/pi-bay dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter pi-bay MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Quels outils pi-bay MCP fournit-il ?
Il expose 12 outils, dont pi_devices_list, pi_device_info, pi_device_authenticate, pi_command_run, pi_files_list.
Que puis-je faire avec pi-bay ?
Vous pouvez trouver des appareils SSH sur votre réseau local, parcourir et modifier des fichiers via SFTP, exécuter des commandes shell et redémarrer des appareils.
Comment me connecter à mes appareils ?
Le serveur se connecte via SSH et peut utiliser les mots de passe enregistrés dans le trousseau de clés de votre système ou les clés SSH existantes de votre agent SSH.
Est-il sûr d'utiliser le mode HTTP pour MCP ?
Non, le mode HTTP ne dispose d'aucune authentification ni de TLS et ne doit être utilisé que sur un réseau local de confiance, car les outils peuvent exécuter des commandes shell et supprimer des fichiers.