flipper-mcp-bridge
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 |
| Devuelve el diccionario |
| Lista los archivos |
| Analiza un archivo |
| Transmite un botón con nombre desde un archivo |
| Transmite una señal IR analizada ad-hoc mediante hex entero con MSB primero (ej. |
| Lista los mandos IR universales integrados disponibles en el firmware (ac, tv, ventiladores, ...) |
| Lista los nombres de señal para un mando universal integrado |
| Transmite una señal con nombre desde un mando universal integrado |
| Pone el Flipper en RX, captura la siguiente pulsación del mando y la añade a un archivo |
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 usbipdLuego (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 / rebootDespués de attach, el Flipper aparecerá en WSL como /dev/ttyACM0.
2. Conceder acceso serie en WSL
sudo usermod -aG dialout $USERLuego reinicia WSL para que el grupo esté activo:
wsl.exe --shutdownReabre tu terminal. groups ahora debería incluir dialout.
3. Instalar dependencias
Desde la raíz del repositorio:
uv sync4. Prueba de funcionamiento
uv run python scripts/smoketest_readonly.pyDeberí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-bridgeAPI REST HTTP (para Home Assistant, curl, scripts):
uv run flipper-mcp-bridge --http --port 8765Endpoints:
Método | Ruta | Cuerpo / Consulta |
|
| — |
|
| — |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 ahttp://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_togglePara 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_PORTDetecció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-bridgeO 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-bridgeLimitaciones conocidas
Latencia de captura:
learn_ir_buttontarda 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 closeuna 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_buttontodavía.Solo IR: Sub-GHz, NFC, RFID, GPIO, BadUSB: ninguno de estos está conectado.
Available Tools
10 toolsdelete_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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Related MCP Servers
- FlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to control TVs on a local network through natural language commands. It currently supports Roku devices, allowing users to launch apps, manage playback, and navigate menus.51-
- AlicenseNot gradedqualityDmaintenanceModular 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.36MIT
- FlicenseBqualityDmaintenanceMCP server for controlling MicroPython devices (ESP32, RP2040, etc.) via USB Serial or WebREPL, enabling code execution, file operations, and device management from MCP clients.299-
- AlicenseAqualityBmaintenanceAn 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.2433 PyPI1MIT