# PlatformIO

Connects PlatformIO toolchains to AI coding agents for building firmware, flashing hardware, and reading serial logs. Designed for microcontroller projects.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 10 repo stars
- Author: powerdragonfire
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/powerdragonfire/platformio.mcp
- Updated: 2026-10-21
- Security check: automated, 2026-11-16 (text) — warning: a command downloads a script from astral.sh and runs it right away. Do not run such commands without an explicit yes from the human.
- HTML: https://affpapa.org/en/nevibecode/mcp/platformio

## What it does

The server gives coding assistants 40 tools to manage microcontroller lifecycles directly. The model runs project builds and tracks syntax issues by file and line number. Unit testing runs through Unity. It handles flashing firmware over a serial cable or over the air via OTA.

Raw terminal dumps stay out of the conversation context. The `pio_flash_and_verify` tool checks board output right after uploading. If an ESP32 crash occurs, the server decodes stack addresses back to specific lines of code. It also inspects memory tables and flash allocation.

You need Python 3.12 and the `uv` runner installed beforehand. The server searches `PATH` and `~/.platformio/penv` for your PlatformIO setup. Missing binaries can be bundled using the `--with-platformio` option.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `PLATFORMIO_MCP_POLICY`, `PLATFORMIO_MCP_PROJECT_DIR`, `PLATFORMIO_MCP_PIO` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env PLATFORMIO_MCP_POLICY=<PLATFORMIO_MCP_POLICY> --env PLATFORMIO_MCP_PROJECT_DIR=<PLATFORMIO_MCP_PROJECT_DIR> --env PLATFORMIO_MCP_PIO=<PLATFORMIO_MCP_PIO> --transport stdio platformio -- uvx platformio.mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from platformio.mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add platformio --env PLATFORMIO_MCP_POLICY=<PLATFORMIO_MCP_POLICY> --env PLATFORMIO_MCP_PROJECT_DIR=<PLATFORMIO_MCP_PROJECT_DIR> --env PLATFORMIO_MCP_PIO=<PLATFORMIO_MCP_PIO> -- uvx platformio.mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from platformio.mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "platformio": {
            "command": "uvx",
            "args": [
                "platformio.mcp"
            ],
            "env": {
                "PLATFORMIO_MCP_POLICY": "<PLATFORMIO_MCP_POLICY>",
                "PLATFORMIO_MCP_PROJECT_DIR": "<PLATFORMIO_MCP_PROJECT_DIR>",
                "PLATFORMIO_MCP_PIO": "<PLATFORMIO_MCP_PIO>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from platformio.mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "platformio": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "platformio.mcp"
            ],
            "env": {
                "PLATFORMIO_MCP_POLICY": "<PLATFORMIO_MCP_POLICY>",
                "PLATFORMIO_MCP_PROJECT_DIR": "<PLATFORMIO_MCP_PROJECT_DIR>",
                "PLATFORMIO_MCP_PIO": "<PLATFORMIO_MCP_PIO>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from platformio.mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e PLATFORMIO_MCP_POLICY=<PLATFORMIO_MCP_POLICY> -e PLATFORMIO_MCP_PROJECT_DIR=<PLATFORMIO_MCP_PROJECT_DIR> -e PLATFORMIO_MCP_PIO=<PLATFORMIO_MCP_PIO> platformio uvx platformio.mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from platformio.mcp <command>

## When to use it
- compile firmware and pinpoint build errors down to the source line
- flash microcontrollers via USB or OTA and verify system startup
- decode ESP32 panic backtraces into file names and line numbers
- inspect flash partition tables and analyze RAM usage
- execute Unity unit test suites on target hardware

## Example prompts
- Build the esp32dev target and show any compiler errors
- Flash the view environment and watch the serial console until setup completes
- Decode the crash backtrace from the serial log and find the failing line

## Similar
- [i2c-bringup-diagnostician](https://affpapa.org/en/nevibecode/skills/i2c-bringup-diagnostician.md) — skill · 134 installs
- [arduino-project-builder](https://affpapa.org/en/nevibecode/skills/arduino-project-builder.md) — skill · 588 installs
- [esp32s3-rlcd42](https://affpapa.org/en/nevibecode/skills/esp32s3-rlcd42.md) — skill · ★ 29 repo stars
- [esp32-wroom-38pin](https://affpapa.org/en/nevibecode/skills/esp32-wroom-38pin.md) — skill · ★ 29 repo stars
- [embedded-iot-mentor](https://affpapa.org/en/nevibecode/skills/embedded-iot-mentor.md) — skill · 22 installs
- [PIO Agent](https://affpapa.org/en/nevibecode/mcp/pio-agent.md) — MCP server · ★ 56 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
