# PIO Agent [Health: Active]

**Category:** 📟 Embedded System  
**Repository:** https://github.com/jl-codes/platformio-mcp  
**GitHub Stars:** 54  
**npm Downloads (last month):** 1270  
**Views:** 9  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/pio-agent

## Description
Build, inspect, flash, and monitor PlatformIO firmware projects with policy-controlled tools.

## Tools
Capabilities this server exposes over MCP:

- **deps_check** — Audit declared and installed project dependencies, with optional separately authorized build and LDF graph evidence.
- **project_envs** — List resolved project environments, inherited board/framework/port settings and configured defaults without running build scripts.
- **project_metadata** — Generate bounded build metadata for selected or all environments. Requires build permission; may execute project scripts or install dependencies.
- **coredump** — Inspect an ESP core dump from a file or explicitly authorized device partition read, optionally analyzing it against an explicit ELF. Device reads can reset hardware and require separate device and host-command grants.
- **partition_table** — Inspect ESP partition artifacts and firmware fit. Optional buildMetadata requires build permission and can execute project scripts. Optional readDevice resets/reads an explicitly selected serial device with separate permissions.
- **run_target** — Run a named PlatformIO target with effect-based permissions. Serial upload targets coordinate owned monitors and endpoint custody; network/probe destinations require their dedicated workflow.
- **list_targets** — List structured target metadata for selected or all environments. Requires build permission; does not execute the listed targets.
- **pkg_search** — Search PlatformIO library, platform or tool registry packages by type and page.
- **pkg_install** — Install a library, platform or tool in a project and save dependencies through PlatformIO.
- **pkg_uninstall** — Remove a library, platform or tool from a project and its declared dependencies.
- **pkg_list** — List project packages and environments. Requires build permission because PlatformIO loads platform code.
- **pkg_outdated** — Report outdated project packages. Requires build permission because PlatformIO loads platform code.
- **pkg_update** — Update project dependencies within declared version constraints, with retained output and configuration change hashes.
- **decode_backtrace** — Decode crash addresses against the selected current or retained ELF. Requires build permission for metadata; does not prove flashed-device identity.
- **size_report** — Report GNU symbols and PlatformIO memory accounting for one environment. Metadata and size checks require build permission and may execute project scripts.
- **list_boards** — Lists all available PlatformIO boards with optional filtering by platform, framework, or MCU. Supports 1000+ boards across 30+ platforms.
- **get_board_info** — Gets detailed information about a specific board including MCU, frequency, flash, RAM, and supported frameworks.
- **list_devices** — Lists all connected serial devices that can be used for firmware upload and monitoring.
- **init_project** — Initializes a new PlatformIO project with the specified board and optional framework. Creates project structure with src/, include/, lib/, and test/ directories.
- **build_project** — Compiles the project and generates the firmware binary via PlatformIO. PREFERRED over running `pio run` directly in a shell — this tool integrates with the hardware lock, the content-hash build cache (skips toolchain work when src/ is unchanged), and a structured-error parser that returns `structuredErrors` + `nextSteps` alongside the raw log. Returns immediately on a cache hit (no compilation). Set `verbose=true` only when you need the full log; otherwise the response stays compact. Use `background=true` for very long first-time builds to avoid MCP timeouts and poll with `check_task_status`.
- **clean_project** — Removes build artifacts and compiled files from the project.
- **upload_filesystem** — Builds and uploads a SPIFFS/LittleFS filesystem image to the connected device. PREFERRED over `pio run --target uploadfs` in a shell — same hardware-lock and port-auto-detect benefits as `upload_firmware`. Supports `start_monitor=true` to re-attach serial after upload.
- **upload_firmware** — Uploads compiled firmware to a connected device. PREFERRED over `pio run --target upload` in a shell — this tool routes through the hardware lock to serialize port access, auto-detects the port, and (with `start_monitor=true`) re-attaches the serial monitor after the device re-enumerates. Automatically rebuilds via `build_project` semantics if the cache is cold.
- **acquire_lock** — Explicitly claim the hardware queue lock for multi-step tasks. Throws if already held.
- **release_lock** — Release the explicit queue lock matching your session ID.
- **get_lock_status** — Reveals who currently owns the hardware queue lock.
- **search_libraries** — Searches the PlatformIO library registry for available libraries by name, keywords, or description.
- **install_library** — Installs a library from the PlatformIO registry either globally or to a specific project. Supports version specification.
- **list_installed_libraries** — Lists all installed libraries either globally or for a specific project.
- **start_monitor** — Manually start or restart the background serial-to-disk spooler for a specific device.
- **stop_monitor** — Kills the active background serial listener and unlocks the UART.
- **query_logs** — Scans the latest active background serial trace spool, returning a filtered string block.
- **reset_server_state** — Forcefully cleans all server locks and terminates any tracked daemon or compilation PIDs globally or locally.
- **check_task_status** — Polls the status of an ongoing background task. Returns a JSON object where `status` indicates the success of the polling operation itself, and `targetStatus` (running, failed, completed) indicates the state of the actual background task.
- **get_dashboard_url** — Retrieves the address and auth token for the MCP Web Dashboard. Automatically starts the web server on demand if offline.
- **get_project_context** — Returns a compact pre-flight snapshot of a PlatformIO project: declared environments, source files under src/, `lib_deps`, build-cache state, firmware artifact path, connected serial devices, and a `nextSteps` checklist. Call this FIRST when starting work on a project instead of issuing several read_file/list_devices/cat-log calls — it collapses that ritual into a single deterministic response. Pure I/O, no toolchain invocation; safe to call repeatedly.
- **get_project_config** — Dumps platformio.ini JSON.
- **agent_validate_project** — Agent-oriented pre-flight validation for a PlatformIO project. Reports environments, board IDs, source-file presence, config gaps, connected devices, and recommended next actions.
- **agent_build_diagnose** — Runs build_project and returns rich structured diagnostics with error taxonomy, evidence, severity, retry-safety, and resource usage (RAM/Flash).
- **agent_safe_pin_audit** — Heuristic static pin audit for board-specific GPIO risks (ESP32 strapping/input-only/flash pins).
- **agent_flash_monitor_verify** — Builds (optionally), flashes firmware with monitor restart, then verifies runtime serial output against expected/rejected patterns and stability criteria.
- **agent_get_last_report** — Returns the last persisted agent report from .pio-mcp-workspace/lastAgentReport.json.
- **agent_generate_board_report** — Generates a compact board intelligence report and caches it in .pio-mcp-workspace/boardReport.json.
- **get_policy_status** — Returns the active policy profile and allowed/approval-required/denied operations.
- **agent_resolve_target** — Resolves exactly one PlatformIO environment, board, and attached physical device. Returns ambiguity instead of guessing and issues a short-lived binding for write workflows.
- **get_monitor_status** — Reports active, inactive, or stale serial monitor state with a bounded incremental cursor.
- **capture_serial_window** — Acquires a bounded serial-monitor lease, captures redacted incremental output, and restores or releases resources on every exit path.
- **agent_monitor_health** — Resolves one device, performs a bounded serial capture, evaluates health markers, and persists change-only automation state when automationKey is provided.
- **cancel_task** — Idempotently cancels one known background task and releases only resources proven to be owned by that task.
- **list_task_history** — Returns compact project-scoped task history after reconciling stale tracked processes.
- **get_approval_request** — Reads one approval request and expiry without exposing approve or deny mutations to the agent.
- **list_pending_approvals** — Lists pending project-scoped approval requests without exposing any approval mutation.
- **system_info** — Gets sys diagnostic path output.
- **check_project** — Static analysis validation.
- **run_tests** — Validates unit tests locally/remote.
- **uninstall_library** — Removes target library.
- **update_library** — Upgrades library versions.
- **serial_session_start** — Start an owned serial monitor using explicit arguments, resolved project settings, or an unambiguous device candidate. Opening requires hardware authorization and exclusive device ownership.
- **serial_session_read** — Read an owned monitor with cursors and bounded Python-compatible regex matching on completed lines. Maximum wait 120 seconds; response and storage byte limits apply.
- **serial_session_write** — Write UTF-8 text to an owned serial session after payload-bound hardware authorization. Limited to 64 KiB including the optional newline.
- **serial_session_list** — List this connection's authorized monitor sessions.
- **serial_session_stop** — Close an owned monitor session, retaining device ownership until closure is confirmed.
- **monitor_capture** — Open, read and close an owned serial monitor. Both opening and reading must be authorized before startup; unconfirmed closure retains device ownership.
- **memory_watch** — Collect bounded heap/stack telemetry from an owned session or an authorized temporary monitor. Reports sample-window trends, explicit unknown units and incomplete collection; does not prove a memory leak.
- **port_diagnose** — Inspect serial-port presence, permissions and observed holders without opening or closing the device. Missing holder evidence does not prove availability.
- **power_profile** — Collect bounded serial current samples or PPK2 meter windows. PPK2 requires explicit mode, voltage/current limits, DUT port plus configured PIO_MCP_PPK2_ENV. An omitted meter port selects one matching PPK2 USB endpoint; ambiguous endpoints require explicit selection. Source mode requires independent power permission. operation=list/cleanup inspects or retries this connection's retained meter cleanup. An owned serial trigger retains DUT custody through meter cleanup. Explicit multi-interface selection pins the observed interface set and retains whole-device exclusion; physical acceptance is pending.
- **debug_start** — Build and start a connection-owned GDB session using PlatformIO's generated initialization, an identified USB probe and a local OpenOCD or J-Link backend. Host execution and target effects require separate permissions. Probe custody remains held until owned descendant groups close.
- **debug_cmd** — Send a classified GDB/MI or console command to this connection's session. Inspection, target mutation and privileged host commands are authorized separately. Timeout does not halt a running target.
- **debug_stop** — Run the configured reset/run hook with host and target permissions, then close owned GDB/backend process groups and release probe custody. Set process_only for recovery without target commands; failed cleanup retains the session for retry.
- **debug_list** — List this connection's debugger sessions, observed target state and pending cleanup. Does not enumerate another connection's sessions or contact hardware.
- **upload_ota** — Upload ESP32/ESP8266 firmware or filesystem images over ArduinoOTA using a fixed network target, immutable image and private credentials. Build and uploader permissions are separate; transfer success does not verify runtime health.
- **flash_verification** — Build and upload firmware, verify fresh owned serial boot output, and decode crashes when authorized. Preserves quiet-window/crash checks; reports incomplete evidence and unverified firmware identity explicitly.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "pio-agent": {
    "command": "npx",
    "args": ["-y","platformio-mcp"]
  }
}
```

## Documentation

## What PIO Agent MCP server does

The PIO Agent MCP server connects agent workflows to PlatformIO projects and supported embedded hardware. It covers board and device discovery, project initialization, configuration inspection, firmware builds, uploads, serial monitoring, and background task management. The same project operations are available through the `platformio-mcp` and `pio-agent` command-line interfaces, while an optional dashboard provides visibility into commands, logs, locks, and safety state.

Agent-focused operations include project validation, structured build diagnosis, board-aware GPIO safety audits, board report generation, target resolution, flash-and-monitor verification, bounded serial health checks, policy inspection, task cancellation, and task history. Reports can be stored in `.pio-mcp-workspace/`, including the latest agent and board reports.

## How it works

The PIO Agent MCP server uses PlatformIO as its first backend and can run as an MCP process for compatible hosts. A manual configuration starts the server with `npx -y platformio-mcp serve`; each connecting session runs its own server process. The CLI is an alternative that executes commands on demand without leaving a server running between invocations.

Commands accept project, board, environment, port, timeout, filtering, and expectation options where applicable. Adding `--json` produces machine-readable output. Background work can be inspected with task-status commands, and monitoring workflows can check expected output or reject known failure patterns.

Operations pass through policy evaluation. Actions may be allowed, denied, or held for approval. Project-level profiles are configured in `.pio-mcp-policy.json`, with options including read-only, build-only, monitor-only, flash-requires-approval, lab-runner, and lab-admin. Risky upload and reset paths remain subject to approval rules, and approvals can be listed, accepted, or denied from the CLI.

## Setup and configuration

Install Node.js 20 or newer and the PlatformIO Core CLI. The recommended package is `platformio-mcp`, which also installs the `platformio-mcp` and `pio-agent` executable names. For example, `pio-agent devices` lists available devices, and `pio-agent build --project-dir . --json` builds a project with JSON output.

The MCP adapter can be added to Claude with the documented `claude mcp add` command or configured manually with an `mcpServers` entry that invokes `npx -y platformio-mcp serve`. The project also provides installation commands for Cline, Claude, VS Code, and Codex, plus a Codex plugin installation path. The optional dashboard starts with `npx platformio-mcp dashboard --serve`.

## Tools and capabilities

The PIO Agent MCP server supports:

- Discovering boards and connected devices.
- Initializing projects and inspecting PlatformIO configuration.
- Building, uploading, monitoring, and polling background tasks.
- Producing structured diagnostics for build, upload, and serial failures.
- Validating project readiness and resolving exact project, environment, and device targets.
- Auditing GPIO safety and generating board intelligence reports.
- Verifying flash and monitor results with expected and rejected serial patterns.
- Reviewing policy, approval, task history, and monitoring health.
- Auditing actions and redacting secrets from exposed log streams.

## Limitations and notes

PlatformIO is currently the first backend, so workflows depend on PlatformIO-supported projects and hardware. Flashing and other risky operations may not run immediately when policy requires human approval. The `lab_runner` profile requires an explicit, expiring unattended-lab policy. MCP sessions started through the host configuration remain separate processes; the CLI avoids that persistent-session model. Physical-board validation is handled separately from the documented automated release checks.

_Full upstream README: https://allmcps.com/mcp/pio-agent/readme_