← Back to pico-bay

Pico Bay

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

pico-bay is an App and MCP Server for managing Raspberry Pi Pico and ESP32 boards with MicroPython and CircuitPython over USB. It runs with Node.js built-in modules and needs no browser extension or runtime npm dependencies.

Quick start

Requires Node.js 20 or newer.

npx pico-bay

Your browser will open automatically! If it doesn't, head to http://localhost:7426. On a Raspberry Pi, open http://PI_HOST_ADDR:7426 from another device on the same network, replacing PI_HOST_ADDR with the Pi's IP address or hostname.

Port 7426 spells PICO on a phone keypad, a nod to the T9 years and flip-phone era.

Devices

Files

Run and console

MCP server

pico-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: pico-bay detects an MCP client on stdin and starts stdio on its own.

{
  "mcpServers": {
    "pico-bay": {
      "command": "npx",
      "args": ["-y", "pico-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 pico-bay --mcp-http

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

{
  "mcpServers": {
    "pico-bay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://PI_HOST_ADDR:7426/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 pico-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 code, overwrite files, reset boards, and permanently delete board files. HTTP mode is intended only for a trusted local network. Do not expose /mcp or pico-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.

MCP tools

Tool Purpose
pico_boards_list List connected boards, stable board IDs, firmware details, and capabilities.
pico_files_list List the board filesystem and report Flash and RAM usage.
pico_file_read Read a text or binary file using UTF-8 or base64.
pico_file_write Create or overwrite a UTF-8 or base64 file, up to 8 MB decoded.
pico_directory_create Create a directory.
pico_path_rename Rename or move a file or directory.
pico_path_delete Permanently delete a file or recursively delete a directory.
pico_python_run Run a file as __main__ or execute Python code and return its output.
pico_board_interrupt Send Ctrl-C to interrupt a running program.
pico_board_reset Soft-reset a board or request a supported hard reset.
pico_board_bootloader Put a board into BOOTSEL or ESP32 download mode for pico_install.
pico_ctrlpi_install Install or update the ctrlPi API agent on a Pico W, Pico 2 W, ESP32, ESP32-S3 or ESP32-C3.
pico_ui Open the web UI in the browser, or return its address when pico-bay runs on another computer. action: "stop" stops it.
pico_install Check and install MicroPython on a Pico in BOOTSEL mode or a supported ESP32 in DOWNLOAD mode.

Call pico_boards_list first, then pass its board_id to board-specific tools. ZIP backup/restore, live console streaming, and Delete all files are intentionally not exposed through MCP.

Installing the ctrlPi API

On a board running MicroPython, Install ctrlPi API in the top-right menu turns it into a ctrlPi agent:

Board Agent Files downloaded from GitHub
Pico W, Pico 2 W pico-gpio-api app.mpy, upgrader.mpy, main.py
ESP32, ESP32-S3, ESP32-C3 esp32-gpio-api app.mpy, boot.py, upgrader.mpy, main.py

app.mpy is the agent, precompiled, upgrader.mpy runs its over-the-air /upgrade, and main.py loads one of them. Fill in the WiFi SSID and password, and optionally an API key and an agent name; pico-bay downloads the latest files, checks them, writes them (main.py last) together with config.json, wifi.txt and a sample scripts/cpu-temp.py sensor for that board, and resets it. The menu item is greyed out on other boards (a Pico without WiFi, or CircuitPython).

On a board that already runs the agent, the form is filled in from its current files, and its existing settings (pins, sensors, bridges) are kept: only the key and name are replaced, and an existing cpu-temp.py is left alone. A blank name keeps the agent's own default, pico-<serial4> or esp32-<serial4>. A blank API key keeps the board's own key, or uses the default your-secret-key on a board without one: that key is public, so change it before relying on the agent.

Installing MicroPython in BOOTSEL mode

On a Pico running MicroPython or CircuitPython, select Reboot to BOOTSEL from the top-right menu and confirm. To enter manually, disconnect the board, hold its BOOTSEL button, and reconnect USB while continuing to hold it. Keep holding for 3 seconds, then release. pico-bay shows the RP2040 or RP2350 boot device as a red pill. Select it and choose if this is a W model (with Wi-Fi) or not, as it is not autodetectable. To cancel before installing firmware, unplug USB and plug it back in without holding any buttons.

pico-bay confirms the operation, downloads the latest matching MicroPython UF2 from micropython.org, validates it, and copies it to the boot volume. The screen reports the download, validation, installation, and reboot stages. Keep the board connected during installation. It reboots automatically and then appears as a normal MicroPython device.

ESP32 download mode

Select Enter download mode… from the top-right menu and confirm. For manual entry, hold BOOT/IO0, press and release RESET / EN, and keep holding BOOT/IO0 for 3 seconds, then release. Alternatively, unplug USB and hold BOOT/IO0. Plug the USB cable back in while continuing to hold BOOT/IO0. Keep holding for 3 seconds, then release. Click Scan in pico-bay, then select the red DOWNLOAD pill to see the detected chip and security details. To cancel before installing firmware, unplug USB and plug it back in without holding any buttons.

Select Install MicroPython to download, validate, install, and verify the latest official generic build. Erase and initialize storage is selected by default and runs after firmware verification, before reboot; uncheck it to preserve existing files. The screen shows each stage and the write progress percentage. Installation uses the ESP32 ROM without extra dependencies and is disabled when the chip is unsupported, unidentified, or protected by flash security.

Requirements

Install

From GitHub:

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

Or install the npm package locally:

npm install pico-bay
npx pico-bay

Options

pico-bay [--port PORT] [--host ADDRESS] [--allow-host NAME] [--hold MILLISECONDS] [--no-open] [--mcp-stdio | --mcp-http | --no-mcp] [--help] [--version]
Option Environment Default Purpose
--port PICO_PORT 7426 Web server port. When the default is busy on a desktop, one of the next 3 is used.
--host PICO_HOST Automatic 127.0.0.1 normally; 0.0.0.0 on a Raspberry Pi host.
--allow-host PICO_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.
--hold PICO_HOLD_MS 900 Idle time before releasing and soft-resetting the board.
--no-open PICO_NO_OPEN false Do not automatically open the default browser on start. Browsers are never opened automatically on Raspberry Pi hosts.
--mcp-stdio PICO_MCP_STDIO false Run only the MCP stdio transport. Optional when an MCP client starts pico-bay: it is detected automatically.
--mcp-http PICO_MCP_HTTP Pi only Add Streamable HTTP MCP at /mcp to the normal web server. Enabled automatically on Raspberry Pi hosts.
--no-mcp PICO_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, pico-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.

Several USB-connected boards may require a powered USB hub and a reliable Raspberry Pi power supply. MicroPython usually uses slightly less power because it exposes only serial; CircuitPython also exposes storage and HID. After an undervoltage event, pico-bay warns that USB may have stopped; fix the power issue and reboot the Pi.

Raspberry Pi OS Lite and other headless installations commonly detect CircuitPython USB storage without mounting it. When udisksctl is available, pico-bay automatically mounts unmounted VFAT partitions labeled CIRCUITPY as the current user, then matches each volume to its board through boot_out.txt. If mounting is unavailable or denied, it falls back to serial access.

BOOTSEL storage may also be detected without being mounted. pico-bay attempts to mount it with udisksctl; if Raspberry Pi OS requires permission, the installation screen shows the command to run on the Pi and a Proceed button to retry afterward.

Only expose pico-bay on a trusted network. It has no login and can modify or erase files on connected boards.

Board access

pico-bay uses the firmware's raw REPL for serial operations. A serial file or board operation briefly interrupts the running program, performs the requested work, and then soft-resets the board so its normal program resumes. Related operations share a short session controlled by --hold; use --hold 0 to release the board after every operation. Toolbar file execution and interactive console commands are available with either firmware.

Reads, writes, uploads, and downloads are binary-safe.

For CircuitPython, pico-bay matches each CIRCUITPY volume by hardware UID. It uses the mounted volume for faster file access when available and serial otherwise. The UI shows read-only only when neither route can write.

When pico-bay stops, it attempts to reset any open board so it is not left halted. Files written to Flash remain after reset; in-memory state does not.

Backups

Download ZIP creates a standard archive of all board files. Restore recreates its files and folders, overwrites matching paths, and leaves other board files untouched. Keep a separate copy of important files before restoring or using Delete all files.

Security

pico-bay can run code, overwrite files, reset a board, and erase its filesystem. It is intended for a trusted local workstation.

Do not expose it to an untrusted network.

Troubleshooting

No board appears

BOOTSEL does not appear

On Linux, check lsusb, lsblk -p -o NAME,LABEL,FSTYPE,MOUNTPOINT, and sudo dmesg | tail -60. USB enumeration errors must be resolved before mounting can work; try another data cable or USB port and check the Pi's power supply. An unmounted RPI-RP2 or RP2350 volume should still appear in Pico Bay.

A command times out

The program restarts after file access

This is expected. Raw-REPL access interrupts the program, and pico-bay resets the board afterward so main.py can resume.

Tests

Run the dependency-free test suite with:

npm test

The test suite covers parsing, ZIP handling, device discovery, HTTP and MCP APIs, and mocked firmware installation. The optional hardware section reports every discovered board, skipping bootloader devices and failing unidentified devices. Other boards continue testing: MicroPython and writable CircuitPython receive temporary file/folder write-read-delete checks; read-only CircuitPython receives capability and console checks. With no devices found, the hardware section is skipped.

Known limits

Related projects

License

MIT