pico-bay

pico-bay is a local Web App and MCP Server for managing MicroPython and CircuitPython boards, such as the Raspberry Pi Pico, 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

Open http://localhost:7426 if it does not open automatically. On a Raspberry Pi host, pico-bay does not launch a browser; open it from another device on the same network instead.

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

Devices

• Supports MicroPython and CircuitPython boards, including the Raspberry Pi Pico, Pico W, Pico 2, and Pico 2 W.
• 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.
• 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. On macOS and other non-Pi hosts, enable MCP with --mcp-stdio or --mcp-http. Streamable HTTP MCP is enabled by default on Raspberry Pi hosts.

stdio

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:

"mcpServers": {
  "pico-bay": {
    "command": "npx",
    "args": ["-y", "@ctrlpi/pico-bay", "--mcp-stdio"]
  }
}

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_ADDRESS with the platform running pico-bay:

"mcpServers": {
  "pico-bay": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "http://PI_ADDRESS: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_install	Check and install firmware on a board in BOOTSEL mode. Currently supports MicroPython.

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 MicroPython in BOOTSEL mode

To enter BOOTSEL mode, disconnect the board, hold its BOOTSEL button, reconnect USB, then release the button. 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.

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

Requirements

• Node.js 20 or newer.
• Raspberry Pi OS, macOS, or Linux. Windows can access pico-bay through a Raspberry Pi but cannot host it.
• A USB-connected board running MicroPython or CircuitPython, or a supported Pico in BOOTSEL mode.
• Permission to open the board's serial device.

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] [--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.
--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. No web server or browser is started.
--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.

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.

• The server listens on 127.0.0.1 by default, or 0.0.0.0 when the host is a Raspberry Pi.
• State-changing requests require the expected HTTP method and same-origin access.
• Device paths reject invalid or traversing path segments.
• The app has no authentication, TLS, authorization, or multi-user isolation.

Do not expose it to an untrusted network.

Troubleshooting

No board appears

• Confirm that the board is running MicroPython or CircuitPython rather than bootloader mode.
• Use a USB data cable and check that its serial device appears under /dev.
• On Linux, check serial permissions, commonly provided by the dialout group.
• Close Thonny, mpremote, screen, and other programs that may own the serial port.

A command times out

• Startup code may be keeping the board busy or disabling interrupts.
• Increase --hold when repeated operations collide with a slow main.py startup.
• Disconnect and reconnect the board to recover an unknown raw-REPL state.

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 single test.js file covers pure parsing and ZIP helpers plus mocked HTTP behavior for both MicroPython and CircuitPython. It also checks for connected serial boards after those tests pass. With no board attached, the hardware section is skipped. MicroPython and writable CircuitPython boards get temporary file/folder write-read-delete checks; read-only CircuitPython boards get non-destructive capability and console checks.

Known limits

• Windows cannot host pico-bay; access it through a Raspberry Pi or another supported host instead.
• Filesystem operations temporarily stop the running application.
• Uploads are limited to 8 MB; ZIP restore supports Store or Deflate with up to 512 files and 16 MB decompressed.
• Concurrent file-change conflict detection is not provided.

License

MIT