# pico-bay MCP server

> Manages Raspberry Pi Pico and ESP32 boards over USB by providing filesystem access, console streaming, and firmware installation.

- Repository: https://github.com/ctrlpi/pico-bay
- Page: https://hostedmcp.org/servers/ctrlpi/pico-bay
- Transport: stdio
- Stars: 10
- License: MIT
- Latest version: 0.9.34

## Install

### Claude Code

```sh
claude mcp add pico-bay -- npx -y @ctrlpi/pico-bay
```

### Cursor (`~/.cursor/mcp.json`)

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

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "pico-bay": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ctrlpi/pico-bay"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"pico-bay","type":"stdio","command":"npx","args":["-y","@ctrlpi/pico-bay"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

```sh
codex mcp add pico-bay -- npx -y @ctrlpi/pico-bay
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.pico-bay]
command = "npx"
args = ["-y", "@ctrlpi/pico-bay"]
```

### Gemini CLI

```sh
gemini mcp add -s user pico-bay npx -- -y @ctrlpi/pico-bay
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## Tools (13)

- `pico_boards_list`: List connected Raspberry Pi Pico and ESP32 boards with MicroPython or CircuitPython and report their capabilities. Use board_id from this result in every other tool. (read-only)
- `pico_files_list`: List the complete board filesystem and report Flash and RAM usage. Hidden files (names starting with .) are omitted unless show_hidden is true. (read-only)
- `pico_file_read`: Read one board file. auto returns UTF-8 text when safe and base64 for binary data; utf8 forces text; base64 always returns base64. (read-only)
- `pico_file_write`: Create or overwrite one board file, creating missing parent directories. content may be UTF-8 text or base64 and is limited to 8 MB decoded.
- `pico_directory_create`: Create one directory on the selected board.
- `pico_path_rename`: Rename or move one file or directory on the selected board.
- `pico_path_delete`: Permanently delete one file or recursively delete one directory from the selected board.
- `pico_python_run`: Run a Python file as __main__ or execute Python code. Provide exactly one of path or code. This can change any state accessible to code on the board. A program still running after timeout_ms is interrupted with Ctrl-C.
- `pico_board_interrupt`: Send Ctrl-C to interrupt the program currently running on the selected board.
- `pico_board_reset`: Soft-reset the selected board, or hard-reset it when the firmware supports hard reset.
- `pico_board_bootloader`: Restart the selected board into firmware install mode: BOOTSEL on a Pico, ROM download mode on an ESP32. The running program stops and the board leaves its normal serial port, so ask the user first. When an ESP32 cannot be reset automatically the result has manual: true and a reason, and the user must hold BOOT while pressing RESET. Afterwards call pico_boards_list, then pico_install with action check.
- `pico_ctrlpi_install`: Install or update the ctrlPi API agent on a Pico W, Pico 2 W, ESP32, ESP32-S3 or ESP32-C3 running MicroPython (pico-gpio-api or esp32-gpio-api, downloaded from GitHub). Writes app.mpy, upgrader.mpy and main.py (plus boot.py on an ESP32), then config.json (the board's own kept, with this api_key and name), wifi.txt and scripts/cpu-temp.py when missing, and resets the board. It replaces main.py, so ask the user first and pass confirmed: true.
- `pico_install`: Install MicroPython on a Pico in BOOTSEL mode or a supported ESP32 in DOWNLOAD mode. Always call action check first. A Pico may require mounting and a Wi-Fi model choice. An ESP32 uses the detected chip-specific generic build. Obtain explicit confirmation before calling action install.

## FAQ

### What boards does pico-bay support?

It supports Raspberry Pi Pico (including Pico W, Pico 2, and Pico 2 W) and various ESP32 boards such as ESP32-S2, ESP32-C3, and ESP32-S3.

### Can I install MicroPython firmware using this tool?

Yes, it can detect RP2040/RP2350 BOOTSEL mode or ESP32 ROM download mode and install the latest MicroPython firmware.

### Is there any authentication for the MCP server?

No, there is no authentication or TLS provided for the MCP server, so it should only be used on a trusted local network.

### How can I run Python code on my board via MCP?

You can use the `pico_python_run` tool to run a file as `__main__` or to execute Python code and receive its output.
