PlatformIO

platformio.mcp

AI コーディングエージェントに実機を操作させましょう。
PlatformIO 用の MCP サーバーです。ビルド、書き込み（シリアルまたは OTA）、シリアルの監視、テストの実行、クラッシュやコアダンプの解析、パーティションテーブルの確認、ヒープと電力の監視、GDB によるデバッグ、ファームウェアのサイズ削減ができます。

Python ネイティブ · Node 不要 · 1 行でインストール · Claude Code、Claude Desktop、Cursor、Codex、Windsurf、Cline に対応

⚡ 60 秒でインストール

uv が必要です（curl -LsSf https://astral.sh/uv/install.sh | sh）。次に、以下を実行します。

uvx platformio.mcp install --claude-code      # or --cursor  --claude-desktop  --codex  --windsurf

このマシンに PlatformIO がない場合は、--with-platformio を追加すると、サーバーと一緒に PlatformIO Core がインストールされます。オプションの追加機能：platformio.mcp[coredump] は ESP32 コアダンプアナライザーを、platformio.mcp[power] は Nordic PPK2 ドライバーを追加します。

uvx platformio.mcp install --print

{ "mcpServers": { "platformio": { "command": "uvx", "args": ["platformio.mcp"] } } }

claude plugin marketplace add powerdragonfire/platformio.mcp   # Claude Code
claude plugin install [email protected]

🎬 動作イメージ

あなた： view 環境に書き込んで、起動することを確認してください。

エージェント → pio_flash_and_verify(env="view", expect="setup done")

FAIL: ファームウェアの書き込みには成功しましたが、起動ログが失敗パターンに一致しました：
'Guru Meditation Error: Core 1 panic'ed (LoadProhibited)'。
原因：LoadProhibited。3/3 個のアドレスを解決しました：
  DisplayTask::run() (display_task.cpp:22) <- DisplayTask::run() (display_task.cpp:23) <- vPortTaskWrapper (port.c:143)

エージェント： display_task.cpp の 22 行目でヌルポインターが発生しています。begin() より前に tft_ が使われています。修正して、再ビルドし、再度書き込みます。

PASS: view 環境への書き込みは 14.2 秒で完了し、2.1 秒間の起動出力の後、/dev/cu.usbserial-0001 で 'setup done' を確認しました。

コンテキストウィンドウに 40 KB のビルドログが入ることはありません。人がシリアルモニターを読む必要もありません。エージェントが受け取るのは、判定結果とファイル名、行番号です。

🔁 エージェントが実行するループ

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

🧰 40 個のツール

すべてのツールは ok、モデル向けに記述された 1 段落の summary、構造化フィールド、および完全な出力を参照する log_path を返します。長い出力は ~/.platformio-mcp/logs のディスク上に保存されます（新しい順に 200 ファイルを保持）。

CLI を超えるツール

🔒 安全ポリシー

サーバーの env で PLATFORMIO_MCP_POLICY を設定するか、install に --policy を渡します。

MCP クライアントも、ツールを呼び出す前に毎回確認を求めます。ポリシーは第 2 の防御層であり、唯一の防御層ではありません。

⚙️ 設定

📝 シリアルモニターに関する注意事項

セッションではポートとの通信に pyserial を直接使用します。PlatformIO 独自のモニターには対話型ターミナルが必要なためです。そのため、esp32_exception_decoder などの PlatformIO モニター用フィルターは適用されません。この処理は pio_decode_backtrace が担います。project_dir を渡すと、ボーレートとポートは platformio.ini の monitor_speed／monitor_port から取得されます。渡さない場合は、検出された単一の開発ボードを 115200 で使用します。ポートを開くとほとんどの開発ボードがリセットされるため、pio_flash_and_verify では起動ログの先頭から確認できます。

🛠️ 開発

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

PyPI リリースの代わりに、チェックアウトしたコードを Claude Code で使用するには、次のようにします。

claude mcp add platformio -- uv run --directory /path/to/platformio.mcp platformio-mcp

変更内容は CHANGELOG.md で追跡しています。

🤝 コントリビュート

実機からのバグ報告が、最も役立つ貢献です。issue forms を利用し、質問は Discussions で行ってください。PR を作成する前に CONTRIBUTING.md をお読みください。good first issue のラベルが付いた Issue は、初めての方に取り組みやすい範囲に設定されています。

🔭 先行事例

jl-codes/platformio-mcp は、同じ目標を持つ TypeScript サーバーで、Web ダッシュボードと GPIO ピン監査機能を備えています。このプロジェクトは、uvx を使って Python のみでインストールでき、PlatformIO 自体の同梱も可能で、クラッシュデコード、サイズの予算管理、パーティションチェック、コアダンプ、OTA、ライブ GDB、メモリ／電力プロファイリングを組み込みで利用したい方のために開発されています。

ライセンス

MIT