npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

platformio-mcp

v3.1.0

Published

PIO Agent: a PlatformIO MCP server and visual control plane for AI-assisted embedded development across 1000+ boards.

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

forkbombforkbomb

Keywords

mcpmodel-context-protocolplatformiopio-agentembeddediotarduinoesp32stm32firmwareembedded-systemsclineclaudeantigravityaidashboard

Readme

PIO Agent

PIO Agent is the open-source, agent-first hardware execution layer for embedded development, built on the PlatformIO MCP runtime.

3.1.0 development status

The parity branch prepares an unreleased 3.1.0 version with optional reference tool aliases, owned serial workflows, retained flash, OTA and expanded distribution candidates. Existing published installations remain 3.0.0. See the unreleased changelog, compatibility guide, and distribution readiness for implemented behavior, remaining acceptance, and which package names are prepared versus published.

Brand and Compatibility

PIO Agent is the product and Codex Plugin name. PlatformIO MCP is the underlying MCP runtime and the compatibility identity used by existing installations. The Codex plugin ID, marketplace ID, configuration keys, and skill namespace remain platformio-mcp. On npm, platformio-mcp is the canonical package while pio-mcp and pio-agent are thin compatibility packages that delegate to it. The canonical package also installs both platformio-mcp and pio-agent executable names. This lets existing consumers upgrade without migration while new users see PIO Agent throughout the interface.

It exposes PlatformIO workflows for board discovery, project setup, build, flash, monitor, diagnostics, and task orchestration through:

  • an MCP server adapter
  • a first-class CLI adapter (platformio-mcp / pio-agent)
  • an optional local dashboard for visibility and control

MCP is one adapter. PlatformIO is the first backend.

Agent-First Capabilities

  • Project readiness validation (agent_validate_project)
  • Rich build diagnostics with structured error taxonomy (agent_build_diagnose)
  • Board-aware GPIO safety audits (agent_safe_pin_audit)
  • Flash + monitor + runtime assertions (agent_flash_monitor_verify)
  • Persistent workflow artifacts in .pio-mcp-workspace/ (lastAgentReport.json, boardReport.json)
  • Board intelligence reports (agent_generate_board_report)
  • Policy profile introspection (get_policy_status)
  • Exact project/environment/device bindings (agent_resolve_target)
  • Bounded, cursor-based serial health checks (agent_monitor_health)
  • Idempotent task cancellation and compact history (cancel_task, list_task_history)
  • Read-only approval status for agents; approval remains human-controlled

All risky operations still honor policy and approval rules.

Quick Start

1. Run the dashboard

npx platformio-mcp dashboard

2. Use the CLI

All three npm names are supported. platformio-mcp is canonical; pio-mcp and pio-agent install the same CLI through thin dependency-only aliases:

npx platformio-mcp --help
npx pio-mcp --help
npx pio-agent --help
npx --package platformio-mcp pio-agent devices
npx --package platformio-mcp pio-agent boards --filter esp32
npx platformio-mcp init --board esp32dev --framework arduino --project-dir ./firmware
npx platformio-mcp build --project-dir ./firmware
npx platformio-mcp flash --project-dir ./firmware --port auto
npx platformio-mcp monitor --project-dir ./firmware --port auto --expect BOOT_OK --timeout 30
npx platformio-mcp agent-validate --project-dir ./firmware
npx platformio-mcp agent-build-diagnose --project-dir ./firmware
npx platformio-mcp agent-safe-pin-audit --project-dir ./firmware --board esp32dev
npx platformio-mcp agent-flash-monitor-verify --project-dir ./firmware --expect-all BOOT_OK --reject-patterns "Guru Meditation,Brownout detector,WDT reset" --timeout 45
npx platformio-mcp agent-last-report --project-dir ./firmware
npx platformio-mcp policy-status --project-dir ./firmware
npx platformio-mcp task-status <task-id>

Use --json for machine-readable output:

npx platformio-mcp build --project-dir ./firmware --json

3. Install into AI hosts

npx platformio-mcp install --cline
npx platformio-mcp install --claude
npx platformio-mcp install --vscode
npx platformio-mcp install --antigravity
npx platformio-mcp install --codex

4. Install the full Codex Plugin

The PIO Agent Codex Plugin adds the bundled MCP runtime, focused embedded skills, secure in-app dashboard flow, and monitoring-automation guidance. Codex requires one stable plugin identifier, so install selectors and skill namespaces remain platformio-mcp; the installed product is shown as PIO Agent. From a clone:

npm install
npm --prefix web install
npm run plugin:build
node build/cli.js install --codex-plugin

From npm:

npx -y platformio-mcp install --codex-plugin

Start a new Codex task after installation. The legacy install --codex command remains available for MCP-only configuration. See the full Codex Plugin guide for update, uninstall, browser fallback, policy, automation, and rollback details.

The plugin release gates run on Windows, macOS, and Linux, exercise the authenticated dashboard in Chromium, validate the bundled runtime and 44-tool registry, and keep physical-board evidence in a separate manual workflow. That workflow uploads only bounded, sanitized evidence; raw hardware logs stay on the self-hosted runner. See the release and validation guide.

For headless verification and status inspection, the same CLI also provides plugin validate, target-resolve, monitor-status, monitor-health, task-history, approval-status, and pending-approvals. Run platformio-mcp --help for bounded options and JSON output support.

Manual MCP Config

{
  "mcpServers": {
    "platformio": {
      "command": "npx",
      "args": ["-y", "platformio-mcp", "--open-dashboard-on-start"]
    }
  }
}

On Windows, use npx.cmd if your host requires explicit shim resolution.

Core Capabilities

  • Board and device discovery for PlatformIO-supported hardware
  • Project initialization and config inspection
  • Build, upload, monitor, and background task polling
  • Structured diagnostics for build/upload/serial failures
  • Safety and policy guardrails (approval gates, audit logs, redaction)
  • Dashboard visibility for commands, logs, locks, and safety state

Safety Model

PIO Agent enforces policy decisions across CLI and MCP flows.

  • Actions can be allow, deny, or requires_approval
  • Risky operations (for example firmware upload/reset paths) require explicit approval
  • All actions can be audited
  • Secrets are redacted in exposed log streams

Policy profiles can be selected per-project via .pio-mcp-policy.json:

{
  "profile": "flash_requires_approval"
}

Supported profiles:

  • read_only
  • build_only
  • monitor_only
  • flash_requires_approval
  • lab_runner (explicit, expiring unattended-lab policy required)
  • lab_admin

CLI approval workflows:

npx platformio-mcp approvals --status pending --json
npx platformio-mcp approve <approval-id> --json
npx platformio-mcp deny <approval-id> --json

Codex Usage

Codex-facing docs and prompt cookbook:

Documentation

Getting started:

Guides and references:

Specifications:

Development

Prerequisites:

  • Node.js >= 20 (including the bundled direct-serial runtime)
  • PlatformIO Core CLI (install guide)

Local setup:

git clone https://github.com/jl-codes/platformio-mcp.git
cd platformio-mcp
npm install
npm run build
npm run test
npm run smoke-test

CI/CD test tiers:

  • npm run test:ci:unit runs unit/component coverage used in cross-platform CI.
  • npm run test:e2e:ci runs CI-safe end-to-end tests for agent workflows and CLI wiring.
  • .github/workflows/ci.yml runs typecheck, tests, and package smoke checks on pull requests/pushes.
  • .github/workflows/hardware-e2e.yml is a manual self-hosted-runner workflow for one explicitly confirmed physical-board write, bundled-plugin protocol checks, post-flash identity/serial assertions, cleanup proof, and sanitized evidence.

Contributing

Contributions are welcome.

  • Open an issue for bugs or feature requests
  • Submit a pull request with tests when applicable

License

MIT. See LICENSE.

Firmware crash and size analysis

The MCP tools decode_backtrace and size_report analyze an explicitly selected project/environment using its registered GNU toolchain. Metadata and memory checks require build permission because they can execute project scripts. Reports identify the exact ELF, retain unresolved crash addresses, and distinguish PlatformIO memory usage from GNU estimates. They do not prove which firmware is on a device. See firmware analysis for inputs, approval behavior, evidence and current limits.