powerdragonfirev0.7.0PythonMIT100Open sourceUpdated 8 days ago
No reviews yet
MCP server that lets AI coding agents drive PlatformIO: build, flash, serial monitor, tests, crash
MCP server that lets AI coding agents drive PlatformIO: build, flash, serial monitor, tests, crash decoding, size reports
·
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.
Use "args": ["platformio.mcp[platformio]"] to bundle PlatformIO Core.
As a plugin (Claude Code, Codex, compatible plugin clients)
Install uv first. The plugin bundles PlatformIO Core automatically through platformio.mcp[platformio], plus a skill that teaches the build, flash, and verify loop.
In Codex's plugin browser (/plugins where supported), add powerdragonfire/platformio.mcp as a marketplace source and select PlatformIO. Restart the client or open a new session after installation. Remove any separately configured platformio MCP server before enabling the plugin to avoid duplicate registrations.
The repo includes portable plugin.json and mcp.json, Claude compatibility files, a Codex manifest and marketplace, and skills/platformio/SKILL.md. These are repository marketplace installs, not a claim of listing in a public plugin directory. See the OpenAI packaging reference and Claude plugin reference.
Other MCP clients can use uvx platformio.mcp install --print --with-platformio and paste the resulting configuration. Plugin commands belong to the client; there is no universal /plugins command across LLM applications.
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.
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
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
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
Registry search and dependency changes that keep platformio.ini in sync; an audit for name collisions, unpinned specs, leftovers, and circular dependencies
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
🔁 Test plans
pio_test_plan_validate / start / status / cancel
A JSON hardware test plan run for N iterations with per-iteration verdicts and evidence logs that record the git and firmware identity
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
What it does
Under the hood
🚀 pio_flash_and_verify
Flash, open the port, read until expect matches (pass), a crash signature matches (fail, auto-decoded), or the timeout passes (timeout)
pio run -t upload + pyserial; fail_on defaults to Guru Meditation, HardFault, abort(), assert failed, watchdog, brownout, heap corruption
🔁 pio_test_plan_*
Run a declarative hardware test plan for N iterations with cancellation, per-iteration verdicts (pass/fail/timeout/infra_error), and evidence logs
Reuses upload + serial monitor tools, continues observing for a post-success window, and writes machine-readable reports with source+firmware identity
🩺 pio_decode_backtrace
Turn an ESP32 Backtrace: 0x400d... dump or a Cortex-M pc/lr dump into function, file, line, inlined frames, cause, reset reason
Toolchain located from pio project metadata, then <target>-addr2line -pfiaC on firmware.elf; fixes Xtensa A0 window bits
📊 pio_size_report
Why is the firmware this big? Flash/RAM %, loaded sections, biggest symbols with file:line, per-file totals, regex filter
pio run -t checkprogsize (partition-aware) + GNU size -A + nm -S -C -l --size-sort
💾 pio_partition_table
Catch the silent ESP32 corruption where an app-only flash leaves an old partition table on the chip; alignment, overlap, OTA slot, and app-fit checks
Parses the env's partition CSV; read_device=true reads 0x8000 with esptool read_flash and diffs
🧯 pio_coredump
Pull the core dump from the coredump partition after a crash and decode task, registers, and backtrace
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.
Set PLATFORMIO_MCP_POLICY in the server's env, or pass --policy to install:
Policy
Can build
Can flash / erase / write serial
Use it for
full (default)
✅
✅
Your own bench
build_only
✅
❌
Shared labs, CI, "look but don't touch"
read_only
❌
❌
Code review, onboarding, untrusted prompts
MCP clients also prompt before each tool call. Policies are the second layer, not the only one.
⚙️ Settings
Variable
Purpose
Default
PLATFORMIO_MCP_POLICY
full, build_only, read_only
full
PLATFORMIO_MCP_PROJECT_DIR
Project used when a tool is called without project_dir
server's cwd
PLATFORMIO_MCP_PIO
Explicit path to the pio executable
auto-detect
PLATFORMIO_MCP_LOG_DIR
Where full command logs go
~/.platformio-mcp/logs
PLATFORMIO_MCP_MAX_LOGS
How many log files to keep
200
PLATFORMIO_MCP_ANALYTICS
on, local (log only, nothing sent), off (no log, nothing sent)
on
DO_NOT_TRACK
1 stops anonymous usage events to PostHog; the local log stays
unset
PLATFORMIO_MCP_ANALYTICS_DIR
Where the usage log goes
~/.platformio-mcp/analytics
PLATFORMIO_MCP_ANALYTICS_URL
Also POST each usage event as JSON to this URL
unset
📊 Usage analytics
Each tool call writes one JSON line to ~/.platformio-mcp/analytics/usage.jsonl on your machine. Releases also send the same event to PostHog EU Cloud (eu.i.posthog.com) as an anonymous event, so the maintainers can see which tools get used and which fail.
An event holds the tool name, ok, the error code, the duration, the names of the arguments passed, the server version, the policy, the OS, the Python version, the MCP client's name and version, and the MCP protocol version. When a tool receives a board or platform argument shaped like a PlatformIO registry id (esp32dev, espressif32), the event keeps that id. A path or URL in those arguments is dropped. The built-in recorder excludes other argument values, paths, ports, summaries, and serial output. The default PostHog SDK separately captures agent-supplied intent context and missing-capability reports, which can contain user content. PostHog sees a random install id from ~/.platformio-mcp/analytics/install_id and no person profile. The first run that sends events prints this notice on stderr.
By default, the built-in recorder sends three PostHog event types in batches of up to 20 events or every 5 seconds, and flushes them when the server shuts down:
Every PostHog event also carries $session_id (a random id per server process, which is one client connection over stdio), $mcp_source, $mcp_client_name, $mcp_client_version, $mcp_protocol_version, $mcp_server_name, $mcp_server_version, $lib, $lib_version, policy, os, and python. The local log and PLATFORMIO_MCP_ANALYTICS_URL get tool calls only, one POST per event.
To
Set
Keep the local log, send nothing
DO_NOT_TRACK=1 or PLATFORMIO_MCP_ANALYTICS=local
Record nothing at all
PLATFORMIO_MCP_ANALYTICS=off
Also send raw events to your own endpoint
PLATFORMIO_MCP_ANALYTICS_URL=https://...
Nothing is sent to PostHog when CI is set, so CI runs do not count as usage.
Version, model, effort, and optional prompts
Both analytics paths report the installed server release as $mcp_server_version and platformio_mcp_version. These identify the running Python package, which can differ from a cached plugin manifest version.
Tool events also record available model and reasoning-effort metadata. Codex supplies model and reasoning_effort in _meta["x-codex-turn-metadata"] (upstream implementation). Other hosts can supply the same fields in _meta["platformio.mcp"]. Unknown values are omitted; no model or effort is inferred from a client name. Model names are bounded identifiers; effort accepts none, minimal, low, medium, high, xhigh, max, or ultra.
Property
Meaning
$mcp_llm_model, $mcp_llm_model_source
Model identifier and client_metadata, SDK self_reported, or configuration source
reasoning_effort, reasoning_effort_source
Supplied effort and client_metadata or configuration source
Optional original prompt, host metadata source, and truncation flag
If the host cannot send model or effort metadata, explicitly set PLATFORMIO_MCP_MODEL and PLATFORMIO_MCP_REASONING_EFFORT in the MCP server environment. Per-call metadata takes precedence. Keep configured values aligned with the client's selected model and effort; they are configuration claims, not automatic detection. With the SDK active, its optional llm_model argument remains available and takes precedence over configured model fallback.
Original prompt capture is off by default. A user must set PLATFORMIO_MCP_CAPTURE_PROMPTS=1 in their MCP server environment and their host must explicitly attach the prompt to each tool request:
{ "_meta": { "platformio.mcp": { "model": "actual-model-id", "reasoning_effort": "high", "prompt": "Build the firmware and inspect the serial output" } } }
The server retains at most the first 2,000 characters of this prompt, including in local logs and custom endpoint events. Enabled remote delivery sends it to PostHog. Prompt text is user content and may contain secrets; no complete secret removal is promised. Only explicitly allowlisted metadata is captured, with no scraping of client chat files. Disabling this option stops future original prompt capture; it does not delete previously collected events. Existing off, local, DO_NOT_TRACK, and CI delivery controls still apply.
Ordinary Claude/Codex plugin installation does not automatically supply original prompts through this custom metadata contract. A host integration must provide it. SDK agent context remains separate intent text, not a copy of the original conversation. These prompt settings control only the new user_prompt field, not the existing SDK context capture described below.
When the SDK is active, report_missing=True exposes a get_more_tools tool. Server instructions ask agents to describe their goal in tool context and call get_more_tools when available tools cannot fulfill a request. Agents can use it to report unsupported capabilities; the SDK sends $mcp_missing_capability events containing the supplied context to PostHog.
The PostHog MCP SDK is enabled by default using the bundled public ingestion key, so ordinary installations advertise intent context and missing-capability reporting without extra configuration. Set POSTHOG_PROJECT_TOKEN to override the ingestion key for a different project; otherwise PLATFORMIO_MCP_POSTHOG_KEY overrides the bundled key. With no non-empty key, the SDK is disabled. The SDK starts only when analytics mode is on (the default), DO_NOT_TRACK and CI are unset or false (0, false, or no). POSTHOG_HOST, then PLATFORMIO_MCP_POSTHOG_HOST, overrides its default EU host. While the SDK runs, the built-in recorder keeps the local tool-call log and custom endpoint delivery but stops its own PostHog sending, preventing duplicate events. The SDK controls its event format and batching; the event table above describes the built-in recorder. Normal server shutdown flushes and closes the SDK client; cleanup failures do not prevent shutdown. Importing the server creates no PostHog client.
Context and missing-capability reports are agent-supplied text, separate from optional original prompt capture, and are sent remotely when analytics is enabled. Agents are instructed to omit secrets and private source code. Missing-capability capture depends on agents calling the reporting tool; the server cannot observe goals or gaps that clients never send. Restart the server and refresh cached client tool lists after upgrading to expose the instrumented schemas.
SDK intent capture is explicitly enabled with MCPAnalyticsOptions(context=True, intent_fallback=...). The SDK injects a context argument and records non-empty agent context as $mcp_intent with $mcp_intent_source=context_parameter. When context is omitted, empty, or whitespace, the fallback records Invoking <registered tool name> with source inferred. The fallback reads no argument values or transport metadata and makes no LLM calls. This identifies the tool operation, not the user's underlying goal. Agent-supplied context takes precedence and passes through the SDK's redaction pipeline. The built-in recorder does not capture intent. See PostHog's intent documentation.
uvx platformio.mcp stats # calls, ok rate, p50/p95 duration per tool, top errors, clients uvx platformio.mcp stats --days 7 --json
The log rotates at 5 MB and keeps one previous file.
📝 Serial monitor notes
Sessions talk to the port with pyserial directly, because PlatformIO's own monitor needs an interactive terminal. PlatformIO monitor filters such as esp32_exception_decoder therefore do not apply; pio_decode_backtrace does that job. Baud and port default from monitor_speed / monitor_port in platformio.ini when project_dir is passed, otherwise the single detected dev board at 115200. Opening the port resets most dev boards, which is why pio_flash_and_verify sees the boot log from the top.
🛠️ Development
git clone https://github.com/powerdragonfire/platformio.mcp && cd platformio.mcp uv sync uv run pytest # unit tests, no hardware or network uv run pytest -m integration # builds the bundled native fixture with your PlatformIO uv run platformio-mcp doctor # what the agent's pio_system_info sees npx @modelcontextprotocol/inspector uv run platformio-mcp # poke tools interactively
To use your checkout in Claude Code instead of the PyPI release:
claude mcp add platformio -- uv run --directory /path/to/platformio.mcp platformio-mcp
Bug reports from real boards are the most useful thing you can send. Use the issue forms, ask questions in Discussions, and read CONTRIBUTING.md before opening a PR. Issues tagged good first issue are scoped for newcomers.
🔭 Prior art
jl-codes/platformio-mcp is a TypeScript server with the same goal, a web dashboard, and a GPIO pin audit. This project exists for people who want a Python-only install through uvx, one that can bundle PlatformIO itself, and crash decoding, size budgeting, partition checks, core dumps, OTA, live GDB, and memory/power profiling built in.
License
MIT
stdioLocal
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
bashmcp.jsonbash~/.codex/config.toml
Run the command below in your terminal.
Restart Claude Code, then check the connection with /mcp.
Open your client's MCP config file, usually mcp.json.
Merge this block into it.
Restart the client to pick up the server.
Run the command below in your terminal.
Reload VS Code and check the MCP section of the Extensions view.
Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Install with your agent
Paste this prompt into your agent. It reads this page and does the setup for you.
prompt
Read https://aiagentslisting.com/mcp/platformio-mcp to learn what the "Platformio Mcp" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.
Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
From the project README
bashbashbash
uvx platformio.mcp install --claude-code # or --cursor --claude-desktop --codex --windsurf uvx platformio.mcp install --print uvx platformio.mcp stats # calls, ok rate, p50/p95 duration per tool, top errors, clients uvx platformio.mcp stats --days 7 --json
npx @modelcontextprotocol/inspector uv run platformio-mcp # poke tools interactively
claude mcp add platformio -- uv run --directory /path/to/platformio.mcp platformio-mcp
This server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
What's missing
Claimed by ownerThe maintainer proved ownership of this listing.
0/4
All 5 checks (4 passed)
Installation methodRequiredThe README documents at least one way to install or connect.
15/15
Has a READMERequiredThe repository ships documentation we could read.
10/10
Easy installA paste-ready client config (an mcpServers block) is documented.
12/12
Has a licenseThe repository declares a license.
8/8
Claimed by ownerThe maintainer proved ownership of this listing.
0/4
Verified liveNot checkableWe connected to the server and it answered a real MCP handshake.
—
Exposes toolsNot checkableThe server reports at least one tool, from its manifest or a live read.
—
Ships promptsNot checkableThe server exposes at least one prompt template.
—
Ships resourcesNot checkableThe server exposes at least one resource.
—
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Paste this line near the top of your repository's README. The badge always renders the current score.
markdown
[](https://aiagentslisting.com/mcp/platformio-mcp)
Connect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "platformio-mcp" with a rating from 1 to 5 and a short note on what worked and what did not.
No reviews yet
Be the first to share your experience with this tool.
Subscribe to our newsletter
One email a week. New agents, MCP servers and skills, and what is actually getting traction.