PlatformIO MCP

platformio.mcp

Dê ao seu agente de codificação de IA acesso a hardware real.
Um servidor MCP para PlatformIO: compile, grave (serial ou OTA), monitore a serial, execute testes, decodifique crashes e core dumps, verifique tabelas de partição, monitore heap e energia, depure via GDB, reduza o firmware.

Python nativo · sem Node · instalação em uma linha · funciona com Claude Code, Claude Desktop, Cursor, Codex, Windsurf, Cline

⚡ Instalação em 60 segundos

Você precisa do uv (curl -LsSf https://astral.sh/uv/install.sh | sh). Então:

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

Sem PlatformIO nesta máquina? Adicione --with-platformio e o servidor traz o PlatformIO Core junto. Extras opcionais: platformio.mcp[coredump] adiciona o analisador de core dump ESP32, platformio.mcp[power] adiciona o driver 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 platformio@platformio.mcp

🎬 Como funciona

Você: grave o env view e garanta que ele inicialize.

Agente → pio_flash_and_verify(env="view", expect="setup done")

FAIL: firmware gravado, mas o log de boot correspondeu ao padrão de falha:
'Guru Meditation Error: Core 1 panic'ed (LoadProhibited)'.
Causa: LoadProhibited. 3/3 endereços resolvidos:
  DisplayTask::run() (display_task.cpp:22) <- DisplayTask::run() (display_task.cpp:23) <- vPortTaskWrapper (port.c:143)

Agente: ponteiro nulo na linha 22 de display_task.cpp, tft_ é usado antes de begin(). Corrigindo, recompilando, gravando novamente.

PASS: env view gravado em 14.2s e 'setup done' visto em /dev/cu.usbserial-0001 após 2.1s de saída de boot.

Sem logs de build de 40 KB na janela de contexto. Sem humano lendo o monitor serial. O agente recebe um veredito, um arquivo e uma linha.

🔁 O loop que o agente executa

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

🧰 As 40 ferramentas

Cada ferramenta retorna ok, um summary de um parágrafo escrito para o modelo, campos estruturados e um log_path para a saída completa. Saída longa permanece em disco em ~/.platformio-mcp/logs (os 200 arquivos mais recentes são mantidos).

As ferramentas que vão além da CLI

🔒 Política de segurança

Defina PLATFORMIO_MCP_POLICY no env do servidor, ou passe --policy para install:

Clientes MCP também solicitam confirmação antes de cada chamada de ferramenta. Políticas são a segunda camada, não a única.

⚙️ Configurações

📝 Notas do monitor serial

As sessões falam com a porta via pyserial diretamente, porque o monitor próprio do PlatformIO precisa de um terminal interativo. Filtros do monitor do PlatformIO, como esp32_exception_decoder, portanto, não se aplicam; pio_decode_backtrace faz esse trabalho. Baud e porta usam padrão de monitor_speed / monitor_port em platformio.ini quando project_dir é passado; caso contrário, a única placa de desenvolvimento detectada a 115200. Abrir a porta redefine a maioria das placas de desenvolvimento, por isso pio_flash_and_verify vê o log de inicialização desde o início.

🛠️ Desenvolvimento

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

Para usar seu checkout no Claude Code em vez do lançamento PyPI:

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

As alterações são rastreadas em CHANGELOG.md.

🤝 Contribuindo

Relatórios de bugs de placas reais são a coisa mais útil que você pode enviar. Use os formulários de issue, faça perguntas em Discussions e leia CONTRIBUTING.md antes de abrir um PR. Issues marcadas com good first issue são escopadas para iniciantes.

🔭 Trabalhos anteriores

jl-codes/platformio-mcp é um servidor TypeScript com o mesmo objetivo, um painel web e uma auditoria de pinos GPIO. Este projeto existe para pessoas que querem uma instalação somente Python via uvx, uma que possa incluir o próprio PlatformIO, e decodificação de crash, orçamento de tamanho, verificações de partição, core dumps, OTA, GDB ao vivo e perfil de memória/energia integrados.

Licença

MIT