Pico Bay

Pico Bay

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 @ctrlpi/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

• Supports Raspberry Pi Pico and ESP32 boards with MicroPython or CircuitPython, including Pico, Pico W, Pico 2, Pico 2 W, ESP32, ESP32-S2, ESP32-C3, and ESP32-S3.
• Detects multiple connected boards and follows USB hot-plug events.
• Detects MicroPython or CircuitPython automatically, including whether its filesystem is read-only or writable.
• Detects RP2040 and RP2350 BOOTSEL mode and installs the latest MicroPython firmware for the selected Pico model.
• Detects Espressif ROM download mode over USB serial, shows the detected chip details, and installs the latest generic MicroPython firmware on supported ESP32 chips.
• Shows Flash and RAM usage for each board.
• Supports soft reset, hard reset, Ctrl-C interruption, and filesystem cleanup.

Files

• Browses the complete filesystem as a searchable, collapsible tree.
• Shows file sizes and modification times when the board provides them.
• Creates, renames, moves, uploads, downloads, and recursively deletes files and folders.
• Opens text files with Python and JSON highlighting.
• Renders a safe Markdown preview without executing embedded HTML.
• Detects binary files and offers them for download instead of displaying them as text.
• Downloads and restores the complete filesystem as a standard ZIP archive.

Run and console

• Runs any Python file as __main__ without replacing main.py.
• Streams program and boot output to a live console.
• Accepts console input and can interrupt a running program with Ctrl-C.

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 enabling stdio:

{

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

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:

app.mpy is the agent, precompiled, upgrader.mpy runs its over-the-air /upgrade, and main.py loads one of them. Fill in the API key, an optional agent name, and the WiFi SSID and password; 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 not shown on other boards (a Pico without WiFi, an ESP32-S2, 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- or esp32- .

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

• Node.js 20 or newer.
• MacOS, Linux, Windows, or Raspberry Pi OS.
• A USB-connected Raspberry Pi Pico or ESP32 board running MicroPython or CircuitPython, or a supported board in bootloader mode.
• Permission to open the board's serial device.
• On Windows, the .NET Framework v4 C# compiler (csc.exe) is required to build the serial helper automatically at startup.
• For ESP32 on Windows, the appropriate serial driver installed (see Troubleshooting).
• For ESP32 resets and download mode on macOS and Linux, Python 3 (standard library only), which drives the DTR and RTS lines.

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 @ctrlpi/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.

--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