What it is
A local workspace for MicroPython and CircuitPython boards, including Pico, Pico W, Pico 2, Pico 2 W, ESP32, ESP32-C3, and ESP32-S3. Plug a board into USB, open the browser, and work with its files and console. The Node server uses built-in modules, with no runtime npm dependencies or browser extension.
Quick start
Run on Windows, Raspberry Pi OS, macOS, or Linux with Node.js 20 or newer and a USB data cable:
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. Port 7426 spells PICO on a phone keypad, a nod to the T9 years.
Your board, in the browser
| Feature | What it does |
|---|---|
| Boards | Detect multiple USB boards, follow hot-plug events, identify firmware, and display Flash and RAM usage. |
| Files | Browse, search, edit, upload, download, rename, and move files and folders. Python and JSON have syntax highlighting. |
| Console | Stream program output, send input, interrupt with Ctrl-C, and run a Python file without replacing main.py. |
| Backups | Download the filesystem as a ZIP archive and restore files and folders from a backup. |
| Firmware | Install MicroPython on supported Pico boards in BOOTSEL mode and ESP32 chips in DOWNLOAD mode, with validation and progress reporting. |
Firmware installation
Put the board in its install mode: for a Pico, choose Reboot to BOOTSEL (or hold BOOTSEL while plugging in USB); for an ESP32, choose Enter download mode… (or hold BOOT/IO0 while pressing RESET/EN). Then select the red board pill and choose Install MicroPython.
The app downloads, validates, installs, and verifies the official generic build. On an ESP32, Erase and initialize storage is on by default; uncheck it to keep existing files.
Windows setup
Windows uses a serial helper compiled automatically at startup. The .NET Framework v4 C# compiler (csc.exe) must be available. Some ESP32 boards also need a USB serial driver, such as CP210x. Check Ports (COM & LPT) in Device Manager if a board does not appear.
Connect an MCP client
Enable HTTP MCP in the app interface or pass --mcp-http. Raspberry Pi hosts enable it by default. Stdio mode (--mcp-stdio) runs only the MCP transport, without a web server or browser.
For an MCP client that launches local servers, add this entry to its MCP configuration:
{
"mcpServers": {
"pico-bay": {
"command": "npx",
"args": ["-y", "@ctrlpi/pico-bay", "--mcp-stdio"]
}
}
}The tools list boards, read and write files, create folders, rename or delete paths, run Python, interrupt or reset a board, and install supported firmware. Start with pico_boards_list, then use its board_id for board operations.
For Streamable HTTP, start the server with:
npx @ctrlpi/pico-bay --mcp-http
MCP is available at http://localhost:7426/mcp, alongside the web interface. Raspberry Pi hosts enable HTTP MCP and listen on the LAN by default. Other hosts listen locally unless you explicitly set --host 0.0.0.0. There is no authentication or TLS, so use a trusted local network.
Working with a running board
Filesystem access temporarily interrupts the board's program through raw REPL, then soft-resets it so normal execution resumes. CircuitPython uses its mounted CIRCUITPY volume when available and serial access otherwise. Close other serial tools before connecting.
ZIP restore overwrites matching paths and leaves other files in place. Keep a separate backup before restoring or deleting files.
In the family
Use pico-bay for firmware, files, and Python over USB on Pico and ESP32 boards. Once pico-gpio-api or esp32-gpio-api is running, ctrlpi-cli and ctrlpi-lab control GPIO over the network.
mcp-bridge exposes those network agents to AI clients, while pico-bay's own MCP tools work directly with USB boards. To put the same pins in Apple Home, use homebridge-ctrlpi.
pi-bay, for network-attached Raspberry Pi boards, is coming soon.