PlatformIO MCP

platformio.mcp

Dale a tu agente de codificación IA manos sobre hardware real.
Un servidor MCP para PlatformIO: compila, flashea (serial u OTA), observa el serial, ejecuta pruebas, decodifica fallos y volcados de núcleo, revisa tablas de particiones, observa heap y energía, depura con GDB, reduce firmware.

Python nativo · sin Node · una línea para instalar · funciona con Claude Code, Claude Desktop, Cursor, Codex, Windsurf, Cline

⚡ Instalación en 60 segundos

Necesitas uv (curl -LsSf https://astral.sh/uv/install.sh | sh). Luego:

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

¿No tienes PlatformIO en esta máquina? Añade --with-platformio y el servidor trae PlatformIO Core consigo. Extras opcionales: platformio.mcp[coredump] añade el analizador de volcados de núcleo ESP32, platformio.mcp[power] añade el controlador 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

🎬 Cómo se ve

Tú: flashea el entorno view y asegúrate de que arranque.

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

FALLO: firmware flasheado pero el registro de arranque coincidió con el patrón de fallo:
'Guru Meditation Error: Core 1 panic'ed (LoadProhibited)'.
Causa: LoadProhibited. 3/3 direcciones resueltas:
  DisplayTask::run() (display_task.cpp:22) <- DisplayTask::run() (display_task.cpp:23) <- vPortTaskWrapper (port.c:143)

Agente: puntero nulo en la línea 22 de display_task.cpp, tft_ se usa antes de begin(). Corrigiendo, recompilando, flasheando de nuevo.

ÉXITO: entorno flasheado en 14.2s y se vio 'setup done' en /dev/cu.usbserial-0001 después de 2.1s de salida de arranque.

Sin registros de compilación de 40 KB en la ventana de contexto. Sin humanos leyendo el monitor serial. El agente obtiene un veredicto, un archivo y una línea.

🔁 El bucle que ejecuta el agente

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

🧰 Las 40 herramientas

Cada herramienta devuelve ok, un summary de un párrafo escrito para el modelo, campos estructurados y un log_path a la salida completa. La salida larga permanece en disco bajo ~/.platformio-mcp/logs (se conservan los 200 archivos más recientes).

Las herramientas que van más allá de la CLI

🔒 Política de seguridad

Establece PLATFORMIO_MCP_POLICY en el env del servidor, o pasa --policy a install:

Los clientes MCP también solicitan confirmación antes de cada llamada a herramienta. Las políticas son la segunda capa, no la única.

⚙️ Configuración

📝 Notas del monitor serie

Las sesiones hablan con el puerto usando pyserial directamente, porque el monitor propio de PlatformIO necesita una terminal interactiva. Por lo tanto, los filtros del monitor de PlatformIO como esp32_exception_decoder no se aplican; pio_decode_backtrace hace ese trabajo. El baud y el puerto se toman por defecto de monitor_speed / monitor_port en platformio.ini cuando se pasa project_dir, de lo contrario, la única placa de desarrollo detectada a 115200. Abrir el puerto reinicia la mayoría de las placas de desarrollo, por eso pio_flash_and_verify ve el registro de arranque desde el principio.

🛠️ Desarrollo

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 tu copia local en Claude Code en lugar de la versión de PyPI:

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

Los cambios se registran en CHANGELOG.md.

🤝 Contribuciones

Los informes de errores de placas reales son lo más útil que puedes enviar. Usa los formularios de problemas, haz preguntas en Discussions y lee CONTRIBUTING.md antes de abrir un PR. Los problemas etiquetados como good first issue están pensados para principiantes.

🔭 Trabajo previo

jl-codes/platformio-mcp es un servidor TypeScript con el mismo objetivo, un panel web y una auditoría de pines GPIO. Este proyecto existe para personas que quieren una instalación solo con Python a través de uvx, una que pueda incluir PlatformIO en sí mismo, y decodificación de fallos, presupuesto de tamaño, comprobaciones de particiones, volcados de núcleo, OTA, GDB en vivo y perfiles de memoria/energía integrados.

Licencia

MIT