Skip to main content
Glama
flipper-mcp-bridge

flipper-mcp-bridge

by dudebot

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

Related MCP server: Flipper Zero MCP Server

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:

  1. 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.

  2. 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:

  1. Argumento explícito port= (solo para uso de biblioteca)

  2. Variable de entorno FLIPPER_PORT

  3. Detección automática: el primer dispositivo conectado cuyo fabricante USB sea "Flipper Devices Inc." (o VID:PID 0483:5740)

  4. 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.

Available Tools

10 tools
delete_ir_buttonB

Remove a named button from an .ir file (reads, filters, rewrites).

Inputs: file (required), button (required).

device_infoA

Return the Flipper's device_info dict (firmware, hardware, radio, etc.).

Inputs: no named parameters. Returns: object

learn_ir_buttonA

Put Flipper in IR RX, wait for a single remote press (up to timeout_seconds), then append the captured signal as a named button to the given .ir file. Creates the file if it doesn't exist. The user must press a physical remote at the Flipper during the capture window.

Inputs: file (required), button (required), timeout_seconds.

list_ir_buttonsB

Parse a saved .ir file on the Flipper and return its buttons.

Inputs: file (required). Returns: result

list_ir_filesA

List .ir files under a directory on the Flipper's SD card (non-recursive).

Inputs: directory. Returns: result

list_universal_remotesA

List the built-in universal IR remote names on this firmware (ac, tv, fans, ...).

Inputs: no named parameters. Returns: result

list_universal_signalsB

List the signal names available for a built-in universal remote (e.g. POWER, VOL+).

Inputs: remote (required). Returns: result

send_ir_buttonB

Transmit a named button from a saved .ir file on the Flipper. Raises on CLI error.

Inputs: file (required), button (required).

send_ir_signalA

Transmit an ad-hoc parsed IR signal. address and command are MSB-first integer hex as reported by ir rx (e.g. protocol='NECext', address='DF02', command='EE11'). Optional '0x' prefix is fine. Raises on CLI error.

Inputs: protocol (required), address (required), command (required).

send_universal_signalB

Transmit a named signal from a built-in universal remote (e.g. remote='ac', signal='OFF').

Inputs: remote (required), signal (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct action or resource: device_info for hardware info, list_* for browsing, learn_* for capturing, send_* for transmitting, and delete_* for removal. No two tools overlap in purpose.

    Naming Consistency4/5

    Most tools follow a verb_ir_noun or verb_universal_noun pattern (e.g., delete_ir_button, send_universal_signal). The one exception is device_info, which uses noun_noun, breaking the pattern slightly.

    Tool Count5/5

    With 10 tools, the server covers the core IR workflows (browse, learn, send, delete) without being overwhelming. The count feels well-scoped for the domain.

    Completeness3/5

    Basic IR operations are covered, but there are gaps: no tool to delete an entire .ir file, rename a file or button, or directly create an empty file. These missing operations may cause workflow dead ends.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Modular MCP server for interacting with a Flipper Zero from MCP-capable clients (including Claude Desktop). Supports system info, BadUSB scripts, and music playback over USB or WiFi.
      36
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that connects to Z-Wave JS UI's WebSocket to expose controller, node, and configuration information as tools for AI assistants to manage Z-Wave networks.
      24
      33 PyPI
      1
      MIT