flipper-mcp-bridge

Servidor MCP que expone un Flipper Zero conectado por USB como un conjunto de herramientas para clientes MCP (Claude Code, Home Assistant a través de un puente compatible, etc.). La v0 se centra en IR: listar/analizar archivos .ir guardados, repetir botones, capturar nuevas señales.

Probado con Momentum firmware (mntm-008). Cualquier fork reciente de Flipper con la misma CLI (ir tx, ir rx, storage *, loader *) debería funcionar.

Herramientas de la v0

Herramienta	Propósito
`device_info`	Devuelve el diccionario `device_info` del Flipper (firmware, hardware, radio)
`list_ir_files`	Lista los archivos `.ir` en un directorio de la tarjeta SD
`list_ir_buttons`	Analiza un archivo `.ir` guardado y devuelve sus botones
`send_ir_button`	Transmite un botón con nombre desde un archivo `.ir` guardado
`send_ir_signal`	Transmite una señal IR analizada ad-hoc mediante hex entero con MSB primero (ej. `NECext DF02 EE11`)
`list_universal_remotes`	Lista los mandos IR universales integrados disponibles en el firmware (ac, tv, ventiladores, ...)
`list_universal_signals`	Lista los nombres de señal para un mando universal integrado
`send_universal_signal`	Transmite una señal con nombre desde un mando universal integrado
`learn_ir_button`	Pone el Flipper en RX, captura la siguiente pulsación del mando y la añade a un archivo `.ir`

Configuración (host Windows, WSL2)

1. Redirigir el USB del Flipper a WSL

Instala usbipd-win en Windows:

winget install usbipd

Luego (desde Windows PowerShell):

usbipd list                          # find the Flipper's BUSID
usbipd bind --busid <X-Y>            # one-time, admin PowerShell
usbipd attach --wsl --busid <X-Y>    # each replug / reboot

Después de attach, el Flipper aparecerá en WSL como /dev/ttyACM0.

2. Conceder acceso serie en WSL

sudo usermod -aG dialout $USER

Luego reinicia WSL para que el grupo esté activo:

wsl.exe --shutdown

Reabre tu terminal. groups ahora debería incluir dialout.

3. Instalar dependencias

Desde la raíz del repositorio:

uv sync

4. Prueba de funcionamiento

uv run python scripts/smoketest_readonly.py

Deberías ver la información del dispositivo, una lista de archivos en /ext/infrared/ y el contenido analizado de cada archivo .ir.

Ejecución

MCP stdio (para Claude Code, Cursor, etc.):

uv run flipper-mcp-bridge

API REST HTTP (para Home Assistant, curl, scripts):

uv run flipper-mcp-bridge --http --port 8765

Endpoints:

Método	Ruta	Cuerpo / Consulta
`GET`	`/health`	—
`GET`	`/device`	—
`GET`	`/ir/files`	`?dir=/ext/infrared`
`GET`	`/ir/buttons`	`?file=/ext/infrared/Remote.ir`
`POST`	`/ir/send-button`	`{"file": "...", "button": "..."}`
`POST`	`/ir/send-signal`	`{"protocol": "...", "address": "...", "command": "..."}`
`GET`	`/ir/universal/list`	`?remote=ac` (omitir para listar mandos disponibles)
`POST`	`/ir/universal/send`	`{"remote": "ac", "signal": "OFF"}`
`POST`	`/ir/learn`	`{"file": "...", "button": "...", "timeout_seconds": 30}`

Integración con Home Assistant

Nota de despliegue: accesibilidad desde HA

HA necesita poder acceder por HTTP al puente. Dos configuraciones sencillas funcionan de inmediato:

Ejecutar el puente en el mismo host que HA (Pi/NUC/servidor con el Flipper conectado). HA accede a http://127.0.0.1:8765. Es lo más sencillo.
Ejecutar el puente en cualquier host Linux siempre encendido en la LAN. Inícialo con --host 0.0.0.0 (la CLI imprime una advertencia: no hay autenticación en la v1, así que haz esto solo en una LAN de confianza). HA accede a http://HOST:8765.

Advertencia sobre WSL2: WSL2 utiliza NAT; la IP de WSL no es accesible desde otros hosts en la LAN. Ejecutar el puente dentro de WSL2 y esperar que HA en un dispositivo diferente lo alcance requiere redirección de puertos netsh interface portproxy en el host Windows, o ejecutar el puente directamente en el host Windows (Python + pyserial funcionan bien en Windows).

Configuración

Añade esto a configuration.yaml:

rest_command:
  flipper_humidifier_toggle:
    url: "http://FLIPPER_HOST:8765/ir/send-button"
    method: POST
    content_type: "application/json"
    payload: '{"file":"/ext/infrared/Remote.ir","button":"Humid"}'

  flipper_ac_off:
    url: "http://FLIPPER_HOST:8765/ir/universal/send"
    method: POST
    content_type: "application/json"
    payload: '{"remote":"ac","signal":"OFF"}'

Luego en automatizaciones o scripts:

action:
  - service: rest_command.flipper_humidifier_toggle

Para una entidad tipo interruptor, usa un interruptor RESTful apuntando al mismo endpoint /ir/send-button (el estado lo mantiene HA, ya que el Flipper no expone el estado del dispositivo).

Selección de puerto

El puente elige un dispositivo serie en este orden de prioridad:

Argumento explícito port= (solo para uso de biblioteca)
Variable de entorno FLIPPER_PORT
Detección automática: el primer dispositivo conectado cuyo fabricante USB sea "Flipper Devices Inc." (o VID:PID 0483:5740)
Alternativa: /dev/ttyACM0

Así que, en el caso común, no necesitas configurar nada. Si tienes múltiples dispositivos CDC y quieres fijar uno específico:

FLIPPER_PORT=/dev/ttyACM1 uv run flipper-mcp-bridge

O añade env a la entrada del servidor en .mcp.json.

Registro en Claude Code

El repositorio incluye un .mcp.json en la raíz; Claude Code lo detecta automáticamente cuando inicias una sesión en este directorio (se te pedirá que lo autorices en el primer lanzamiento). Si prefieres registrarlo explícitamente:

claude mcp add flipper -- uv run --directory "$(pwd)" flipper-mcp-bridge

Limitaciones conocidas

Latencia de captura: learn_ir_button tarda unos segundos antes de que el Flipper empiece a escuchar realmente. Pulsa el mando un momento después de llamar a la herramienta, no inmediatamente.
Transporte: Solo CLI sobre serie. El RPC de Protobuf aún no está implementado. Está bien para IR a ritmo humano; podría revisarse para flujos sensibles al rendimiento.
Bloqueado por aplicaciones en primer plano: si una aplicación que no es la CLI posee el Flipper (ej. la pantalla de espera del reloj de noche), la transmisión IR está bloqueada. El puente intenta loader close una vez en caso de conflicto, pero algunas aplicaciones solo pueden cerrarse manualmente en el dispositivo.
Captura IR cruda no soportada: las señales de protocolos desconocidos no funcionarán de ida y vuelta mediante learn_ir_button todavía.
Solo IR: Sub-GHz, NFC, RFID, GPIO, BadUSB: ninguno de estos está conectado.