# PIO Agent (npm · platformio-mcp)

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

- Trust score: 88/100 (high trust)
- Change this week: +6
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-10-16

## Components

- npm · `platformio-mcp`: 88/100 (this document), [markdown](https://verifymcp.io/servers/jl-codes-platformio-mcp/platformio-mcp.md), [page](https://verifymcp.io/servers/jl-codes-platformio-mcp/platformio-mcp)

## Channel facts

- Registry: `npm`
- Package: `platformio-mcp`
- Version: `3.1.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-10-16.

- **Supply Chain Security**: 98/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 43 of 146 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to jl-codes/platformio-mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 20 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 71/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 7381 tokens (~102/item across 72 items; 72 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 70/100
  - Stability observed for 21 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 78/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 33% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - All 5 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation.
  - An AI judge read all 72 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the PIO Agent MCP server?

PIO Agent runs locally as an npm package, launched with npx -y platformio-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add jl-codes-platformio-mcp -- npx -y platformio-mcp
```

### Cursor

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

### VS Code

```json
{
  "servers": {
    "jl-codes-platformio-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "platformio-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add jl-codes-platformio-mcp -- npx -y platformio-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jl-codes-platformio-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "platformio-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add jl-codes-platformio-mcp --command npx --arg -y --arg platformio-mcp
```

### Hermes

```yaml
mcp_servers:
  jl-codes-platformio-mcp:
    command: "npx"
    args: ["-y", "platformio-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "jl-codes-platformio-mcp": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "platformio-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add jl-codes-platformio-mcp -t stdio -c npx -a -y platformio-mcp
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-10-16 (score 88, +1)

No change was recorded against any check on this day. Stability & Change Management went from 67 to 70. That category is still filling its 30-day observation window: 20 days of observed history at the previous scan, 21 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-14 (score 87, +1)

No change was recorded against any check on this day. Stability & Change Management went from 60 to 63. That category is still filling its 30-day observation window: 18 days of observed history at the previous scan, 19 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-13 (score 86, 0)

- [functional regression] Security disclosure: unverified → fail

### 2026-10-12 (score 86, +1)

No change was recorded against any check on this day. Stability & Change Management went from 53 to 57. That category is still filling its 30-day observation window: 16 days of observed history at the previous scan, 17 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-11 (score 85, +3)

- [functional regression] Security disclosure: fail → unverified

### 2026-10-03 (score 82, +9)

- [security improvement] Source repository: unverified → pass
- [functional improvement] Stability: unverified → 0.27

### 2026-10-02 (score 73, −5)

- [security regression] Provenance: pass → unverified

### 2026-09-28 (score 78, 0)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

## MCP tools (72)

### `deps_check` (~83 tokens)

Audit declared and installed project dependencies, with optional separately authorized build and LDF graph evidence.

Input parameters:

- `approvalId` (string)
- `build` (boolean)
- `buildApprovalId` (string)
- `configurationApprovalId` (string)
- `environment` (string)
- `inventoryApprovalId` (string)
- `projectDir` (string, required)

### `project_envs` (~44 tokens)

List resolved project environments, inherited board/framework/port settings and configured defaults without running build scripts.

Input parameters:

- `approvalId` (string)
- `projectDir` (string, required)

### `project_metadata` (~53 tokens)

Generate bounded build metadata for selected or all environments. Requires build permission; may execute project scripts or install dependencies.

Input parameters:

- `approvalId` (string)
- `environment` (string)
- `projectDir` (string, required)

### `coredump` (~177 tokens)

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.

Input parameters:

- `analyze` (boolean)
- `approvalId` (string)
- `commandApprovalId` (string)
- `device` (object)
- `dumpPath` (string)
- `elfPath` (string)
- `encrypted` (boolean)
- `expectedElfSha256` (string)
- `expectedInputSha256` (string)
- `exportApprovalId` (string)
- `format` (string)
- `outPath` (string)
- `projectDir` (string, required)
- `retainDump` (boolean): Save the device partition in private managed storage with 24-hour expiry; requires export permission.

### `partition_table` (~232 tokens)

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.

Input parameters:

- `approvalId` (string)
- `boardApprovalId` (string)
- `buildMetadata` (boolean): Generate build metadata under build permission; may execute project scripts.
- `commandApprovalId` (string)
- `configApprovalId` (string)
- `environment` (string)
- `firmwarePath` (string)
- `flashSize` (integer)
- `format` (string)
- `metadataApprovalId` (string)
- `observedTablePath` (string)
- `port` (string)
- `projectDir` (string, required)
- `readApprovalId` (string)
- `readDevice` (boolean): Read the partition sector from an explicit serial port; may reset hardware and requires separate device and host-command permissions.
- `sdkconfigPath` (string)
- `systemApprovalId` (string)
- `tableOffset` (integer)
- `tablePath` (string)

### `run_target` (~105 tokens)

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.

Input parameters:

- `approvalId` (string)
- `configApprovalId` (string)
- `environment` (string|null)
- `projectDir` (string, required)
- `selectionApprovalId` (string)
- `stopOpenSessions` (boolean)
- `target` (string, required)
- `uploadPort` (string|null)

### `list_targets` (~52 tokens)

List structured target metadata for selected or all environments. Requires build permission; does not execute the listed targets.

Input parameters:

- `approvalId` (string)
- `environment` (string)
- `projectDir` (string, required)

### `pkg_search` (~52 tokens)

Search PlatformIO library, platform or tool registry packages by type and page.

Input parameters:

- `approvalId` (string)
- `kind` (string)
- `page` (integer)
- `query` (string, required)

### `pkg_install` (~62 tokens)

Install a library, platform or tool in a project and save dependencies through PlatformIO.

Input parameters:

- `approvalId` (string)
- `environment` (string)
- `kind` (string)
- `projectDir` (string, required)
- `spec` (string, required)

### `pkg_uninstall` (~61 tokens)

Remove a library, platform or tool from a project and its declared dependencies.

Input parameters:

- `approvalId` (string)
- `environment` (string)
- `kind` (string)
- `projectDir` (string, required)
- `spec` (string, required)

### `pkg_list` (~47 tokens)

List project packages and environments. Requires build permission because PlatformIO loads platform code.

Input parameters:

- `approvalId` (string)
- `environment` (string)
- `projectDir` (string, required)

### `pkg_outdated` (~47 tokens)

Report outdated project packages. Requires build permission because PlatformIO loads platform code.

Input parameters:

- `approvalId` (string)
- `environment` (string)
- `projectDir` (string, required)

### `pkg_update` (~47 tokens)

Update project dependencies within declared version constraints, with retained output and configuration change hashes.

Input parameters:

- `approvalId` (string)
- `environment` (string)
- `projectDir` (string, required)

### `decode_backtrace` (~133 tokens)

Decode crash addresses against the selected current or retained ELF. Requires build permission for metadata; does not prove flashed-device identity.

Input parameters:

- `approvalId` (string)
- `archivedElfSha256` (string): Retained ELF hash from this environment source path, for an earlier build.
- `environment` (string, required): Explicit build environment; metadata collection can execute project scripts.
- `expectedElfSha256` (string)
- `includeAllHex` (boolean)
- `projectDir` (string, required): Explicit PlatformIO project directory.
- `text` (string, required): Crash output, at most 1 MiB UTF-8.

### `size_report` (~107 tokens)

Report GNU symbols and PlatformIO memory accounting for one environment. Metadata and size checks require build permission and may execute project scripts.

Input parameters:

- `approvalId` (string)
- `environment` (string, required): Explicit build environment; metadata collection can execute project scripts.
- `expectedElfSha256` (string)
- `filter` (string): Case-insensitive bounded regex applied to symbol names or source paths.
- `projectDir` (string, required): Explicit PlatformIO project directory.
- `top` (integer)

### `list_boards` (~71 tokens)

Lists all available PlatformIO boards with optional filtering by platform, framework, or MCU. Supports 1000+ boards across 30+ platforms.

Input parameters:

- `filter` (string): Optional filter by platform (e.g., "espressif32"), framework (e.g., "arduino"), or MCU name

### `get_board_info` (~58 tokens)

Gets detailed information about a specific board including MCU, frequency, flash, RAM, and supported frameworks.

Input parameters:

- `boardId` (string, required): Board ID (e.g., "esp32dev", "uno", "nucleo_f401re")

### `list_devices` (~23 tokens)

Lists all connected serial devices that can be used for firmware upload and monitoring.

### `init_project` (~121 tokens)

Initializes a new PlatformIO project with the specified board and optional framework. Creates project structure with src/, include/, lib/, and test/ directories.

Input parameters:

- `board` (string, required): Board ID for the project
- `framework` (string): Optional framework (e.g., "arduino", "espidf", "mbed")
- `platformOptions` (object): Optional platform-specific configuration options
- `projectDir` (string, required): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.

### `build_project` (~286 tokens)

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`.

Input parameters:

- `background` (boolean): If true, dispatches the compilation to the background and returns immediately to prevent MCP timeouts. You must poll status subsequently.
- `environment` (string): Optional specific environment to build from platformio.ini
- `forceExecution` (boolean): Run a fresh build even when inputs match the cache
- `jobs` (integer): Optional parallel build jobs
- `projectDir` (string, required): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.
- `sessionId` (string): Agent session ID for pipeline lock validation
- `verbose` (boolean): If true, returns the complete verbose build log in the result instead of truncating it on success

### `clean_project` (~127 tokens)

Removes build artifacts and compiled files from the project.

Input parameters:

- `background` (boolean): If true, dispatches the long-running execution to the background and returns immediately to prevent MCP timeouts. You must poll status subsequently.
- `environment` (string): Optional environment to clean
- `full` (boolean): Also remove downloaded build dependencies using fullclean
- `projectDir` (string, required): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.
- `sessionId` (string): Agent session ID for pipeline lock validation

### `upload_filesystem` (~293 tokens)

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.

Input parameters:

- `automationKey` (string): Stable scheduled-run key. Supplying this activates unattended automation policy.
- `background` (boolean): If true, dispatches the compilation to the background and returns immediately to prevent MCP timeouts. You must poll status subsequently.
- `environment` (string): Optional specific environment from platformio.ini
- `maxRunDurationSeconds` (integer): Required finite execution budget for an unattended write.
- `port` (string): Optional upload port (auto-detected if not specified)
- `projectDir` (string, required): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.
- `sessionId` (string): Agent session ID for pipeline lock validation
- `start_monitor` (boolean): If true, automatically starts the background serial monitor after a successful upload, handling OS-level port re-enumeration.
- `targetBinding` (object): Short-lived exact target binding returned by agent_resolve_target.
- `verbose` (boolean): If true, returns the complete verbose upload log in the result instead of truncating it

### `upload_firmware` (~311 tokens)

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.

Input parameters:

- `automationKey` (string): Stable scheduled-run key. Supplying this activates unattended automation policy.
- `background` (boolean): If true, dispatches the compilation to the background and returns immediately to prevent MCP timeouts. You must poll status subsequently.
- `environment` (string): Optional specific environment from platformio.ini
- `maxRunDurationSeconds` (integer): Required finite execution budget for an unattended write.
- `port` (string): Optional upload port (auto-detected if not specified)
- `projectDir` (string, required): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.
- `sessionId` (string): Agent session ID for pipeline lock validation
- `start_monitor` (boolean): If true, automatically starts the background serial monitor after a successful upload, handling OS-level port re-enumeration.
- `targetBinding` (object): Short-lived exact target binding returned by agent_resolve_target.
- `verbose` (boolean): If true, returns the complete verbose upload log in the result instead of truncating it

### `acquire_lock` (~47 tokens)

Explicitly claim the hardware queue lock for multi-step tasks. Throws if already held.

Input parameters:

- `reason` (string): Reason for locking
- `sessionId` (string, required): Your active Session ID

### `release_lock` (~30 tokens)

Release the explicit queue lock matching your session ID.

Input parameters:

- `sessionId` (string, required): Your active Session ID

### `get_lock_status` (~19 tokens)

Reveals who currently owns the hardware queue lock.

### `search_libraries` (~59 tokens)

Searches the PlatformIO library registry for available libraries by name, keywords, or description.

Input parameters:

- `limit` (number): Maximum number of results (default: 20)
- `query` (string, required): Search query (library name, keyword, or description)

### `install_library` (~122 tokens)

Installs a library from the PlatformIO registry either globally or to a specific project. Supports version specification.

Input parameters:

- `global` (boolean): If true, performs the operation globally. Defaults to false.
- `library` (string, required): Library name or ID to install
- `projectDir` (string): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.
- `version` (string): Optional specific version (e.g., "1.0.0", "^2.1.0")

### `list_installed_libraries` (~76 tokens)

Lists all installed libraries either globally or for a specific project.

Input parameters:

- `global` (boolean): If true, performs the operation globally. Defaults to false.
- `projectDir` (string): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.

### `start_monitor` (~105 tokens)

Manually start or restart the background serial-to-disk spooler for a specific device.

Input parameters:

- `baudRate` (number): Optional baud rate. Defaults to 115200.
- `environment` (string): Optional PlatformIO environment context.
- `port` (string): Optional COM path. Falls back to default.
- `projectDir` (string): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.

### `stop_monitor` (~69 tokens)

Kills the active background serial listener and unlocks the UART.

Input parameters:

- `port` (string, required): COM port to stop listening on.
- `projectDir` (string): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.

### `query_logs` (~114 tokens)

Scans the latest active background serial trace spool, returning a filtered string block.

Input parameters:

- `lines` (number): Fetch this many tail lines from the end of the log (default: 100)
- `port` (string): Specific COM port to query logs for.
- `projectDir` (string): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.
- `searchPattern` (string): Optional Regex pattern to filter the spool for specific keywords.

### `reset_server_state` (~64 tokens)

Forcefully cleans all server locks and terminates any tracked daemon or compilation PIDs globally or locally.

Input parameters:

- `projectDir` (string): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.

### `check_task_status` (~120 tokens)

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.

Input parameters:

- `logPath` (string): Optional relative log path to check.
- `projectDir` (string): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.
- `taskId` (string): Optional task ID to check status.

### `get_dashboard_url` (~54 tokens)

Retrieves the address and auth token for the MCP Web Dashboard. Automatically starts the web server on demand if offline.

Input parameters:

- `open` (boolean): If true, automatically opens the authenticated GUI link natively in the system's browser.

### `get_project_context` (~161 tokens)

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.

Input parameters:

- `includeBuildHistory` (boolean): If true, include the most recent build/upload status summary from the workspace log directory.
- `projectDir` (string, required): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.

### `get_project_config` (~50 tokens)

Dumps platformio.ini JSON.

Input parameters:

- `projectDir` (string, required): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.

### `agent_validate_project` (~56 tokens)

Agent-oriented pre-flight validation for a PlatformIO project. Reports environments, board IDs, source-file presence, config gaps, connected devices, and recommended next actions.

Input parameters:

- `projectDir` (string, required): Path to the PlatformIO project directory.

### `agent_build_diagnose` (~103 tokens)

Runs build_project and returns rich structured diagnostics with error taxonomy, evidence, severity, retry-safety, and resource usage (RAM/Flash).

Input parameters:

- `background` (boolean): If true, dispatches build to background and returns a pending diagnostic status.
- `environment` (string): Optional specific environment from platformio.ini.
- `projectDir` (string, required): Path to the PlatformIO project directory.
- `verbose` (boolean): If true, preserves verbose build output.

### `agent_safe_pin_audit` (~60 tokens)

Heuristic static pin audit for board-specific GPIO risks (ESP32 strapping/input-only/flash pins).

Input parameters:

- `boardId` (string, required): Target PlatformIO board ID.
- `projectDir` (string, required): Path to the PlatformIO project directory.

### `agent_flash_monitor_verify` (~211 tokens)

Builds (optionally), flashes firmware with monitor restart, then verifies runtime serial output against expected/rejected patterns and stability criteria.

Input parameters:

- `autoBuild` (boolean): If true, builds before flashing when firmware artifact is missing.
- `automationKey` (string): Stable scheduled-run key. Supplying this activates unattended automation policy.
- `environment` (string): Optional specific environment from platformio.ini.
- `expect_all` (array): Serial markers expected to appear.
- `maxRunDurationSeconds` (integer): Required finite execution budget for an unattended write.
- `port` (string): Optional upload port.
- `projectDir` (string, required): Path to the PlatformIO project directory.
- `reject_patterns` (array): Serial patterns that must not appear.
- `stabilityWindowSeconds` (number): Required quiet window in seconds (default 10).
- `targetBinding` (object): Short-lived exact target binding returned by agent_resolve_target.
- `timeoutSeconds` (number): Verification window in seconds (default 45).

### `agent_get_last_report` (~44 tokens)

Returns the last persisted agent report from .pio-mcp-workspace/lastAgentReport.json.

Input parameters:

- `projectDir` (string, required): Path to the PlatformIO project directory.

### `agent_generate_board_report` (~59 tokens)

Generates a compact board intelligence report and caches it in .pio-mcp-workspace/boardReport.json.

Input parameters:

- `boardId` (string, required): Target PlatformIO board ID.
- `projectDir` (string, required): Path to the PlatformIO project directory.

### `get_policy_status` (~41 tokens)

Returns the active policy profile and allowed/approval-required/denied operations.

Input parameters:

- `projectDir` (string): Optional project directory to resolve local policy profile context.

### `agent_resolve_target` (~87 tokens)

Resolves exactly one PlatformIO environment, board, and attached physical device. Returns ambiguity instead of guessing and issues a short-lived binding for write workflows.

Input parameters:

- `bindingTtlSeconds` (integer)
- `environment` (string): Optional declared PlatformIO environment.
- `port` (string): Optional exact attached serial port.
- `projectDir` (string, required): Exact PlatformIO project directory.

### `get_monitor_status` (~50 tokens)

Reports active, inactive, or stale serial monitor state with a bounded incremental cursor.

Input parameters:

- `port` (string): Optional exact serial port.
- `projectDir` (string): Optional exact PlatformIO project directory.

### `capture_serial_window` (~125 tokens)

Acquires a bounded serial-monitor lease, captures redacted incremental output, and restores or releases resources on every exit path.

Input parameters:

- `automationKey` (string): Stable scheduled-run key. Supplying this activates unattended automation policy.
- `baudRate` (integer)
- `cursor` (string)
- `durationSeconds` (integer)
- `environment` (string)
- `maxBytes` (integer)
- `port` (string)
- `projectDir` (string, required)
- `targetBinding` (object): Short-lived exact target binding returned by agent_resolve_target.

### `agent_monitor_health` (~122 tokens)

Resolves one device, performs a bounded serial capture, evaluates health markers, and persists change-only automation state when automationKey is provided.

Input parameters:

- `automationKey` (string)
- `baudRate` (integer)
- `captureDurationSeconds` (integer)
- `cursor` (string)
- `environment` (string)
- `expectedMarkers` (array)
- `failureThreshold` (integer)
- `maxBytes` (integer)
- `port` (string)
- `projectDir` (string, required)
- `rejectedPatterns` (array)

### `cancel_task` (~45 tokens)

Idempotently cancels one known background task and releases only resources proven to be owned by that task.

Input parameters:

- `projectDir` (string)
- `taskId` (string, required)

### `list_task_history` (~46 tokens)

Returns compact project-scoped task history after reconciling stale tracked processes.

Input parameters:

- `limit` (integer)
- `projectDir` (string, required)
- `status` (string)

### `get_approval_request` (~42 tokens)

Reads one approval request and expiry without exposing approve or deny mutations to the agent.

Input parameters:

- `approvalId` (string, required)
- `projectDir` (string)

### `list_pending_approvals` (~39 tokens)

Lists pending project-scoped approval requests without exposing any approval mutation.

Input parameters:

- `limit` (integer)
- `projectDir` (string)

### `system_info` (~14 tokens)

Gets sys diagnostic path output.

### `check_project` (~132 tokens)

Static analysis validation.

Input parameters:

- `background` (boolean): Run slow analysis in background
- `environment` (string): Specific environment to check
- `pattern` (string): Source file pattern
- `projectDir` (string, required): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.
- `severity` (string): Minimum defect severity
- `skipPackages` (boolean): Exclude dependency source files
- `structuredReport` (boolean): Request JSON analysis and return structured defects for foreground calls
- `tool` (string): Configured analysis tool

### `run_tests` (~196 tokens)

Validates unit tests locally/remote.

Input parameters:

- `background` (boolean): Run testing in background
- `compileOnly` (boolean): Compile tests without uploading or executing them. Enforced by build_only policy.
- `environment` (string): Specific environment to test
- `filter` (string): Include matching test suites
- `ignore` (string): Exclude matching test suites
- `projectDir` (string, required): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.
- `structuredReport` (boolean): Include per-case results for foreground runs; cannot be combined with background
- `uploadPort` (string): Explicit test upload port
- `verbose` (boolean): Verbose test output
- `withoutBuilding` (boolean): Use existing test artifacts; incompatible with compile-only
- `withoutUploading` (boolean): Skip upload; test execution may still access hardware

### `uninstall_library` (~78 tokens)

Removes target library.

Input parameters:

- `global` (boolean): If true, performs the operation globally. Defaults to false.
- `library` (string, required): Library name or ID to uninstall
- `projectDir` (string): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.

### `update_library` (~79 tokens)

Upgrades library versions.

Input parameters:

- `global` (boolean): If true, performs the operation globally. Defaults to false.
- `library` (string, required): Library name or ID to update
- `projectDir` (string): Path to the PlatformIO project directory. Agents SHOULD ALWAYS explicitly provide this to ensure operations execute in the correct workspace, unless explicitly instructed otherwise.

### `serial_session_start` (~118 tokens)

Start an owned serial monitor using explicit arguments, resolved project settings, or an unambiguous device candidate. Opening requires hardware authorization and exclusive device ownership.

Input parameters:

- `approval_id` (string)
- `baud` (integer|null)
- `config_approval_id` (string)
- `discovery_approval_id` (string)
- `env` (string|null)
- `max_lines` (integer)
- `port` (string|null)
- `project_dir` (string|null)
- `selection_approval_id` (string)

### `serial_session_read` (~87 tokens)

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.

Input parameters:

- `approval_id` (string)
- `cursor` (integer)
- `max_lines` (integer)
- `session_id` (string, required)
- `timeout_s` (number)
- `wait_for` (string|null)

### `serial_session_write` (~66 tokens)

Write UTF-8 text to an owned serial session after payload-bound hardware authorization. Limited to 64 KiB including the optional newline.

Input parameters:

- `approval_id` (string)
- `newline` (boolean)
- `session_id` (string, required)
- `text` (string, required)

### `serial_session_list` (~25 tokens)

List this connection's authorized monitor sessions.

Input parameters:

- `approval_id` (string)

### `serial_session_stop` (~31 tokens)

Close an owned monitor session, retaining device ownership until closure is confirmed.

Input parameters:

- `session_id` (string, required)

### `monitor_capture` (~139 tokens)

Open, read and close an owned serial monitor. Both opening and reading must be authorized before startup; unconfirmed closure retains device ownership.

Input parameters:

- `approval_id` (string)
- `baud` (integer|null)
- `config_approval_id` (string)
- `discovery_approval_id` (string)
- `env` (string|null)
- `max_lines` (integer)
- `port` (string|null)
- `project_dir` (string|null)
- `read_approval_id` (string)
- `seconds` (number)
- `selection_approval_id` (string)
- `until` (string|null)

### `memory_watch` (~182 tokens)

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.

Input parameters:

- `approval_id` (string)
- `baud` (integer|null)
- `config_approval_id` (string)
- `discovery_approval_id` (string)
- `env` (string|null)
- `max_lines` (integer)
- `pattern` (string|null)
- `port` (string|null)
- `project_dir` (string|null)
- `read_approval_id` (string)
- `seconds` (number)
- `selection_approval_id` (string)
- `session_id` (string|null)
- `stack_unit` (string)
- `stack_warn_bytes` (integer)
- `stack_word_bytes` (integer)

### `port_diagnose` (~97 tokens)

Inspect serial-port presence, permissions and observed holders without opening or closing the device. Missing holder evidence does not prove availability.

Input parameters:

- `approval_id` (string)
- `config_approval_id` (string)
- `env` (string|null)
- `monitor_approval_id` (string)
- `port` (string|null)
- `project_dir` (string|null)
- `selection_approval_id` (string)

### `power_profile` (~374 tokens)

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.

Input parameters:

- `approval_id` (string)
- `baud` (integer)
- `buckets` (integer)
- `config_approval_id` (string)
- `current_limit_ma` (number)
- `discovery_approval_id` (string)
- `dut_port` (string)
- `env` (string|null)
- `host_approval_id` (string)
- `max_lines` (integer)
- `mode` (string)
- `operation` (string)
- `pattern` (string|null)
- `port` (string|null)
- `power_approval_id` (string)
- `power_operation_id` (string)
- `profile_approval_id` (string)
- `project_dir` (string|null)
- `provenance` (string)
- `read_approval_id` (string)
- `seconds` (number)
- `selection_approval_id` (string)
- `sleep_threshold_ma` (number|null)
- `source` (string)
- `trigger` (string|null)
- `trigger_approval_id` (string)
- `trigger_seconds` (number): Trigger wait limit; defaults to seconds when omitted.
- `trigger_session_id` (string|null)
- `voltage_mv` (number|null)

### `debug_start` (~219 tokens)

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.

Input parameters:

- `approval_id` (string)
- `backend_host_approval_id` (string)
- `backend_target_approval_id` (string)
- `build_approval_id` (string)
- `config_approval_id` (string)
- `discovery_approval_id` (string)
- `env` (string|null)
- `image_approval_id` (string)
- `initialization_host_approval_id` (string)
- `initialization_target_approval_id` (string)
- `load` (boolean)
- `probe` (object)
- `project_dir` (string|null)
- `request_approval_id` (string)
- `resolution_approval_id` (string)
- `system_approval_id` (string)
- `timeout_s` (number)

### `debug_cmd` (~95 tokens)

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.

Input parameters:

- `approval_id` (string)
- `command` (string, required)
- `request_approval_id` (string)
- `session_id` (string, required)
- `target_approval_id` (string)
- `timeout_s` (number)

### `debug_stop` (~104 tokens)

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.

Input parameters:

- `host_approval_id` (string)
- `process_only` (boolean)
- `request_approval_id` (string)
- `session_id` (string, required)
- `target_approval_id` (string)
- `timeout_s` (number)

### `debug_list` (~43 tokens)

List this connection's debugger sessions, observed target state and pending cleanup. Does not enumerate another connection's sessions or contact hardware.

Input parameters:

- `request_approval_id` (string)

### `upload_ota` (~215 tokens)

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.

Input parameters:

- `approval_id` (string)
- `auth` (string|null)
- `build` (boolean)
- `build_approval_id` (string)
- `command_approval_id` (string)
- `config_approval_id` (string)
- `elf_path` (string)
- `env` (string|null)
- `expected_image_sha256` (string)
- `filesystem` (boolean)
- `host` (string, required)
- `image_approval_id` (string)
- `image_path` (string)
- `port` (integer|null)
- `project_dir` (string|null)
- `resolve_approval_id` (string)
- `system_approval_id` (string)
- `timeout_s` (number)
- `verify_reachable` (boolean)

### `flash_verification` (~275 tokens)

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.

Input parameters:

- `approval_id` (string)
- `baud` (integer|null)
- `config_approval_id` (string)
- `decode_approval_id` (string)
- `decode_config_approval_id` (string)
- `discovery_approval_id` (string)
- `env` (string|null)
- `expect` (string)
- `fail_on` (string)
- `manifest_approval_id` (string)
- `max_lines` (integer)
- `monitor_approval_id` (string)
- `monitor_port` (string|null)
- `preflight_discovery_approval_id` (string)
- `project_dir` (string|null)
- `read_approval_id` (string)
- `resume_id` (string)
- `selection_approval_id` (string)
- `settle_s` (number)
- `stability_window_s` (number)
- `stop_open_sessions` (boolean)
- `system_approval_id` (string)
- `timeout_s` (number)
- `upload_port` (string|null)
- `workflow_approval_id` (string)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/jl-codes-platformio-mcp/platformio-mcp#diagnostics

## Score history

- 2026-10-16: 88
- 2026-10-15: 87
- 2026-10-14: 87
- 2026-10-13: 86
- 2026-10-12: 86
- 2026-10-11: 85
- 2026-10-04: 82
- 2026-10-03: 82
- 2026-10-02: 73
- 2026-10-01: 78
- 2026-09-30: 78
- 2026-09-29: 78
- 2026-09-28: 78
- 2026-09-27: 78
- 2026-09-26: 78
- 2026-09-25: 78

## Common questions

### What is the PIO Agent MCP server?

PIO Agent is an MCP server listed in the public MCP registry as io.github.jl-codes/platformio-mcp. Build, inspect, flash, and monitor PlatformIO firmware projects with policy-controlled tools. This page covers its npm package (platformio-mcp).

### Is the PIO Agent MCP server safe to use?

PIO Agent scores 88 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 16 October 2026. It declares no install or post-install scripts. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the PIO Agent MCP server expose?

PIO Agent exposes 72 tools: deps_check, project_envs, project_metadata, coredump, partition_table, and 67 more. Their descriptions and schemas cost roughly 7,381 tokens of context every time the server is loaded.

### Is the PIO Agent MCP server still maintained?

PIO Agent is still listed as active in the MCP registry. We last reached this channel on 16 October 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the PIO Agent MCP server under?

PIO Agent declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- npm package: https://www.npmjs.com/package/platformio-mcp
- Socket report: https://socket.dev/npm/package/platformio-mcp
- Repository: https://github.com/jl-codes/platformio-mcp
- Changelog RSS feed: https://verifymcp.io/servers/jl-codes-platformio-mcp/platformio-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/jl-codes-platformio-mcp/platformio-mcp.json
- HTML version of this page: https://verifymcp.io/servers/jl-codes-platformio-mcp/platformio-mcp