PlatformIO

本地服务

github.com开发工具66 周前更新

代码仓库访问官网

关于 PlatformIO

PlatformIO 是一个 MCP 服务，让 AI 编码 Agent 操作 PlatformIO 项目和连接的硬件。它涵盖固件构建与烧录、测试、串口监控、调试、崩溃分析和资源报告。

主要功能

01构建并烧录固件
02监控串口输出
03运行测试和静态检查
04解码崩溃及核心转储
05通过 GDB 调试
06检查内存、功耗和固件大小

适用场景

01构建并烧录嵌入式项目
02根据启动日志验证设备启动
03将崩溃定位到源代码
04检查固件内存与功耗

MCP 相关

该服务向 MCP 客户端提供 PlatformIO 项目、构建、硬件、测试、监控、分析和调试工具。策略可将权限限制为仅构建或只读。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "powerdragonfire-platformio": {
      "command": "uvx",
      "args": [
        "platformio.mcp"
      ],
      "env": {
        "PLATFORMIO_MCP_POLICY": "<PLATFORMIO_MCP_POLICY>",
        "PLATFORMIO_MCP_PROJECT_DIR": "<PLATFORMIO_MCP_PROJECT_DIR>",
        "PLATFORMIO_MCP_PIO": "<PLATFORMIO_MCP_PIO>"
      }
    }
  }
}

启动命令uvx platformio.mcp

需要配置的环境变量

PLATFORMIO_MCP_POLICYfull (default), build_only, or read_only

PLATFORMIO_MCP_PROJECT_DIRDefault project directory when a tool is called without project_dir

PLATFORMIO_MCP_PIOExplicit path to the pio executable (auto-detected otherwise)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiplatformio.mcp0.1.0stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

platformio.mcp

让 AI 编码 Agent 能够在真实硬件上动手操作。
一个适用于 PlatformIO 的 MCP 服务：构建、烧录（串口或 OTA）、监控串口、运行测试、解码崩溃和核心转储、检查分区表、监控堆和功耗、通过 GDB 调试、缩减固件。

原生 Python · 无需 Node · 一行即可安装 · 适用于 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 驱动。

其他 MCP 客户端（Cline、Zed、Continue 等）

uvx platformio.mcp install --print

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

使用 "args": ["platformio.mcp[platformio]"] 来打包 PlatformIO Core。

作为插件（Claude Code、Cursor：服务 + 教授工作循环的技能）

此仓库遵循 Open Plugins 布局：.mcp.json、skills/platformio/SKILL.md、rules/platformio.mdc、plugin.json。

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

已经安装 PlatformIO？

服务会在 PATH 或 ~/.platformio/penv 中查找 platformio / pio。使用 PLATFORMIO_MCP_PIO=/path/to/pio 覆盖。运行 uvx platformio.mcp doctor，查看 Agent 将看到的内容。

🎬 效果示例

你：烧录 view 环境，并确认它能启动。

Agent → 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)
Agent： display_task.cpp 第 22 行的空指针，tft_ 在 begin() 前就被使用。正在修复、重新构建并再次烧录。
PASS：已在 14.2 秒内烧录 view 环境，并在 /dev/cu.usbserial-0001 上的启动输出 2.1 秒后看到 'setup done'。

上下文窗口中不会塞满 40 KB 的构建日志，也不需要人工盯着串口监视器。Agent 会得到结论、文件和行号。

🔁 Agent 执行的工作循环

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 个工具

分组	工具	Agent 获取的内容
🔍 发现	`pio_system_info` · `pio_list_boards` · `pio_board_info` · `pio_list_devices`	PlatformIO 版本和策略；约 1,700 种开发板的 MCU、时钟频率、RAM 和 Flash 容量；串口，并标记可能的开发板
📁 项目	`pio_project_init` · `pio_project_envs` · `pio_project_metadata`	实际运行的 `pio project init`（绝不手写 ini）；每个环境的开发板、框架、监视器和上传设置；定义和包含路径
🔨 构建与烧录	`pio_build` · `pio_upload` · `pio_upload_ota` · `pio_clean` · `pio_list_targets` · `pio_run_target`	状态、已解析的错误和警告（文件、行、列）、RAM/Flash 使用率、最近 40 行内容、完整日志路径。额外目标，如 `buildfs`、`erase`。通过 Wi-Fi 向 ArduinoOTA 开发板进行 OTA 更新。端口故障会分类报告（忙碌、权限不足、缺失、无响应），并提供修复方法
📟 串口	`pio_monitor_start` / `read` / `write` / `stop` / `list` · `pio_monitor_capture` · `pio_port_diagnose`	带环形缓冲区、游标读取和 `wait_for` 正则表达式的后台会话；或无需管理的单次捕获。端口诊断：占用端口的对象（我们的会话或其他进程）、权限及修复方法
✅ 验证	`pio_test` · `pio_check`	Unity 测试的逐个用例通过/失败状态和消息；按严重性列出 cppcheck / clang-tidy 缺陷及 CWE 编号
📦 软件包	`pio_pkg_search` / `install` / `uninstall` / `list` / `outdated` / `update` · `pio_deps_check`	注册表搜索，以及保持 `platformio.ini` 同步的依赖项变更；检查名称冲突、未锁定版本的规范、残留项和循环依赖
🧠 分析	`pio_flash_and_verify` · `pio_decode_backtrace` · `pio_size_report`	硬件在环测试的通过/失败状态；解析崩溃转储并定位到文件:行；查看 Flash 和 RAM 中每个字节的用途
💾 Flash 布局	`pio_partition_table` · `pio_coredump`	ESP32 分区 CSV 检查（对齐、重叠、容量、OTA 槽位），并与芯片上的实际分区表进行差异比较；从 Flash 中提取并解码核心转储
📈 运行时	`pio_memory_watch` · `pio_power_profile`	从串口解析的堆和栈遥测数据，包含泄漏判断和每个任务的余量；从串口电流表或 Nordic PPK2 获取电流消耗，区分休眠/活动状态并估算电池续航
🐞 调试	`pio_debug_start` / `cmd` / `stop` / `list`	通过 `pio debug` 建立实时 GDB 会话：断点、单步、回溯、变量，并将 MI 记录解析为结构化结果

每个工具都会返回 ok、面向模型编写的一段式 summary、结构化字段，以及指向完整输出的 log_path。较长的输出会保存在磁盘上的 ~/.platformio-mcp/logs 中（保留最新的 200 个文件）。

超越 CLI 的工具

	功能	底层实现
🚀 `pio_flash_and_verify`	烧录、打开端口，并读取内容，直到匹配 `expect`（通过）、匹配崩溃特征（失败，自动解码），或超时（超时）	`pio run -t upload` + pyserial；`fail_on` 默认为 Guru Meditation、HardFault、`abort()`、`assert failed`、watchdog、brownout、heap corruption
🩺 `pio_decode_backtrace`	将 ESP32 的 `Backtrace: 0x400d...` 转储或 Cortex-M 的 `pc`/`lr` 转储转换为函数、文件、行号、内联帧、原因和重置原因	从 `pio project metadata` 定位工具链，然后对 `firmware.elf` 执行 `<target>-addr2line -pfiaC`；修复 Xtensa `A0` 窗口位
📊 `pio_size_report`	固件为什么这么大？闪存/RAM 占比、已加载区段、最大的符号及其 `file:line`、每个文件的总计、正则表达式 `filter`	`pio run -t checkprogsize`（感知分区）+ GNU `size -A` + `nm -S -C -l --size-sort`
💾 `pio_partition_table`	检测 ESP32 上静默发生的损坏：仅烧录应用会让芯片保留旧分区表；检查对齐、重叠、OTA 槽和应用适配性	解析环境的分区 CSV；`read_device=true` 会通过 `esptool read_flash` 读取 0x8000 并进行差异比较
🧯 `pio_coredump`	崩溃后从 `coredump` 分区提取核心转储，并解码任务、寄存器和回溯信息	`esptool read_flash` + 可选的 `esp-coredump info_corefile`（`platformio.mcp[coredump]`）
📈 `pio_memory_watch`	根据固件已有的输出，判断内存泄漏、碎片化和栈余量	解析 `Free heap:`、`heap_caps_print_heap_info`、`vTaskList`、`uxTaskGetStackHighWaterMark` 行；最小二乘斜率
🔋 `pio_power_profile`	电流平均值/最小值/最大值/p95、睡眠与活动状态占比、能耗、电池续航估算	串口电表（INA219 草图、USB 电表日志）或 Nordic PPK2（`platformio.mcp[power]`）
🐞 *`pio_debug_`**	通过调试探针进行断点设置、单步执行、回溯和变量检查	通过 GDB/MI 驱动 `pio debug --interface=gdb`，并解析 `*stopped` 事件
🌐 `pio_upload_ota`	通过 Wi-Fi 烧录，并将失败原因对应到解决方法（密码错误、未调用 `ArduinoOTA.handle()`、防火墙、没有 OTA 槽）	`pio run -t upload --upload-port <ip>`（自动切换到 espota）或直接运行 `espota.py`
🔌 `pio_port_diagnose`	上传操作为何无法打开端口：我们的会话、其他进程、权限问题，或开发板未处于引导加载程序模式	`lsof`/`fuser` + `pio device list`；绝不会终止任何进程
📚 `pio_deps_check`	库名称冲突（`lib_deps` 顺序会静默决定胜出者）、未固定版本的规格、残留项和循环依赖	`.pio/libdeps` 和 `lib/` 中的清单，以及设置 `build=true` 后的 LDF 依赖关系图

🔒 安全策略

在服务端的 env 中设置 PLATFORMIO_MCP_POLICY，或在安装时传入 --policy：

策略	可以构建	可以烧录 / 擦除 / 写入串口	适用场景
`full`（默认）	✅	✅	自己的工作台
`build_only`	✅	❌	共享实验室、CI、“只看不动”
`read_only`	❌	❌	代码审查、入门培训、不可信的提示词

MCP 客户端也会在每次调用工具前提示确认。策略是第二层防护，而非唯一防护。

⚙️ 设置

变量	用途	默认值
`PLATFORMIO_MCP_POLICY`	`full`、`build_only`、`read_only`	`full`
`PLATFORMIO_MCP_PROJECT_DIR`	调用工具时未提供 `project_dir` 的情况下使用的项目	服务端的 cwd
`PLATFORMIO_MCP_PIO`	`pio` 可执行文件的明确路径	自动检测
`PLATFORMIO_MCP_LOG_DIR`	完整命令日志的保存位置	`~/.platformio-mcp/logs`
`PLATFORMIO_MCP_MAX_LOGS`	保留的日志文件数量	`200`

📝 串口监视器说明

会话使用 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

若要在 Claude Code 中使用本地检出版本，而非 PyPI 发行版：

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

更改记录在 CHANGELOG.md 中。

🤝 贡献

来自真实开发板的错误报告最有帮助。请使用问题表单，在 Discussions 中提问，并在提交 PR 前阅读 CONTRIBUTING.md。标记为 good first issue 的问题适合新手参与。

🔭 相关项目

jl-codes/platformio-mcp 是一个目标相同的 TypeScript 服务，还提供 Web 仪表盘和 GPIO 引脚审计。本项目面向希望通过 uvx 进行纯 Python 安装的用户，可将 PlatformIO 本身打包在内，并内置崩溃解码、大小预算、分区检查、核心转储、OTA、实时 GDB 以及内存和功耗分析功能。

许可证

MIT

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。