PlatformIO MCP

PlatformIO MCP is the open-source, agent-first hardware execution layer for embedded development.

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)

All risky operations still honor policy and approval rules.

Quick Start

1. Run the dashboard

npx platformio-mcp dashboard

2. Use the CLI

npx platformio-mcp devices
npx platformio-mcp 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 

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

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

PlatformIO MCP 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
• flash_requires_approval
• lab_admin

CLI approval workflows:

npx platformio-mcp approvals --status pending --json
npx platformio-mcp approve  --json
npx platformio-mcp deny  --json

Codex Usage

Codex-facing docs and prompt cookbook:

• Codex Usage Guide
• Codex Prompt Cookbook

Documentation

Getting started:

• LLM Installation Guide

Guides and references:

• Agent Customization Guide
• MCP Server Command Reference
• Troubleshooting Guide
• Agent-First Embedded Workflow
• Competitive Positioning
• MCP-U Integration Template
• Agent Skills Directory

Specifications:

• PIO MCP Design Specification
• Web UX Design Specification
• Development Guide

Development

Prerequisites:

• Node.js >= 18
• 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 real hardware MCP E2E (RUN_MCP_E2E=1).

Contributing

Contributions are welcome.

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

License

MIT. See LICENSE.