PlatformIO

platformio.mcp

Give your AI coding agent hands on real hardware.

An MCP server for PlatformIO : build, flash (serial or OTA), watch serial, run tests, decode crashes and core dumps, check partition tables, watch heap and power, debug over GDB, shrink firmware.

Python native · no Node · one line to install · works with Claude Code, Claude Desktop, Cursor, Codex, Windsurf, Cline

---

⚡ 60-second install

You need uv (curl -LsSf https://astral.sh/uv/install.sh | sh). Then:

uvx platformio.mcp install --claude-code      # or --cursor  --claude-desktop  --codex  --windsurf

No PlatformIO on this machine? Add --with-platformio and the server brings PlatformIO Core along. Optional extras: platformio.mcp[coredump] adds the ESP32 core-dump analyzer, platformio.mcp[power] adds the Nordic PPK2 driver.

Any other MCP client (Cline, Zed, Continue, ...)

uvx platformio.mcp install --print

{ "mcpServers": { "platformio": { "command": "uvx", "args": ["platformio.mcp"] } } }

Use "args": ["platformio.mcp[platformio]"] to bundle PlatformIO Core.

As a plugin (Claude Code, Cursor: server + a skill that teaches the loop)

The repo follows the Open Plugins layout: .mcp.json, skills/platformio/SKILL.md, rules/platformio.mdc, plugin.json.

claude plugin marketplace add powerdragonfire/platformio.mcp   # Claude Code

claude plugin install platformio@platformio.mcp

</details>

Already have PlatformIO?

The server finds platformio / pio on your PATH or in ~/.platformio/penv. Override with PLATFORMIO_MCP_PIO=/path/to/pio. Run uvx platformio.mcp doctor to see what the agent will see.

🎬 What it looks like

You: flash the view env and make sure it boots.

Agent → pio_flash_and_verify(env="view", expect="setup done")

`

FAIL: firmware flashed but the boot log matched the failure pattern:

'Guru Meditation Error: Core 1 panic'ed (LoadProhibited)'.

Cause: LoadProhibited. 3/3 addresses resolved:

DisplayTask::run() (display_task.cpp:22) <- DisplayTask::run() (display_task.cpp:23) <- vPortTaskWrapper (port.c:143)

`

Agent: null pointer on line 22 of display_task.cpp, tft_ is used before begin(). Fixing, rebuilding, flashing again.

`

PASS: flashed env view in 14.2s and saw 'setup done' on /dev/cu.usbserial-0001 after 2.1s of boot output.

`

No 40 KB build logs in the context window. No human reading the serial monitor. The agent gets a verdict, a file and a line.

🔁 The loop the agent runs

flowchart LR

A[pio_project_envs] --> B[edit code] B --> C[pio_build] C -- errors with file:line --> B C -- ok --> D[pio_flash_and_verify] D -- PASS --> E([done]) D -- FAIL: decoded backtrace --> B D -- TIMEOUT --> F[pio_monitor_capture] F --> B

🧰 The 40 tools

Group Tools What the agent gets back

🔍 Discover pio_system_info · pio_list_boards · pio_board_info · pio_list_devices PlatformIO version and policy; ~1,700 boards with MCU, clock, RAM and flash sizes; serial ports with the likely dev boards flagged

📁 Project pio_project_init · pio_project_envs · pio_project_metadata A real pio project init (never a hand-written ini); every env with board, framework, monitor and upload settings; defines and include paths

🔨 Build & flash pio_build · pio_upload · pio_upload_ota · pio_clean · pio_list_targets · pio_run_target Status, parsed errors and warnings (file, line, column), RAM/Flash %, last 40 lines, full log path. Extra targets like buildfs , erase . OTA over Wi-Fi to ArduinoOTA boards. Port failures come back classified (busy, permission, missing, no response) with the fix

📟 Serial pio_monitor_start / read / write / stop / list · pio_monitor_capture · pio_port_diagnose Background sessions with a ring buffer, cursor reads, and wait_for regex; or a one-shot capture with nothing to manage. Port diagnosis: who holds it (our session, another process), permissions, the fix

✅ Verify pio_test · pio_check Unity tests with per-case pass/fail and messages; cppcheck / clang-tidy defects by severity with CWE ids

📦 Packages pio_pkg_search / install / uninstall / list / outdated / update · pio_deps_check Registry search and dependency changes that keep platformio.ini in sync; an audit for name collisions, unpinned specs, leftovers, and circular dependencies

🧠 Analyse pio_flash_and_verify · pio_decode_backtrace · pio_size_report Hardware-in-the-loop pass/fail; crash dumps resolved to file:line; where every byte of flash and RAM goes

💾 Flash layout pio_partition_table · pio_coredump ESP32 partition CSV checks (alignment, overlap, fit, OTA slots) and a diff against the table actually on the chip; core dump pulled from flash and decoded

📈 Runtime pio_memory_watch · pio_power_profile Heap and stack telemetry parsed from serial with a leak verdict and per-task headroom; current draw from a serial meter or a Nordic PPK2 with sleep/active split and battery estimate

🐞 Debug pio_debug_start / cmd / stop / list A live GDB session over pio debug : breakpoints, step, backtrace, variables, with MI records parsed into structured results

Every tool returns ok, a one-paragraph summary written for the model, structured fields, and a log_path to the full output. Long output stays on disk under ~/.platformio-mcp/logs (newest 200 files kept).

The tools that go beyond the CLI

🔁 Repeatable hardware test plans

Use declarative JSON plans when you need reproducible board validation over many iterations.

{

"plan_version": 1, "name": "SPI loopback", "project_dir": "/abs/project", "environment": "ch32h4_loopback", "device_identity": "bench-ch32h4-01", "board": { "platformio_env": "ch32h4_loopback", "board_id": "genericCH32H4" }, "peripherals": ["SPI loopback"], "pin_mapping": { "SPI_MOSI": "PB15", "SPI_MISO": "PB14" }, "fixture": { "required_wiring": ["PB15 to PB14"] }, "run": { "iterations": 100, "upload_each_iteration": true, "stop_open_sessions": true }, "serial_assertion": { "success_pattern": "SPI_LOOPBACK_OK", "failure_pattern": "panic|HardFault|assert failed|test-failure", "timeout_s": 20, "observation_window_s": 5, "reconnect_attempts": 1 } }

Workflow:

1. pio_test_plan_validate(plan_path=...)
2. pio_test_plan_start(plan_path=...)
3. poll pio_test_plan_status(run_id=...)
4. optional cancel: pio_test_plan_cancel(run_id=...)

Reports include source revision + dirty state, firmware hash, selected env, and detected device identity. Every non-pass iteration stores evidence logs with references in the JSON report.

An end-to-end CH32H4 fixture + firmware example is in examples/ch32h4-spi-loopback.

🔒 Safety policy

Set PLATFORMIO_MCP_POLICY in the server's env, or pass --policy t