flipper-mcp-bridge
flipper-mcp-bridge
MCP-Server, der einen per USB angeschlossenen Flipper Zero als eine Reihe von Werkzeugen für MCP-Clients (Claude Code, Home Assistant über eine kompatible Bridge usw.) bereitstellt. v0 konzentriert sich auf IR: Auflisten/Parsen von gespeicherten .ir-Dateien, Wiederholen von Tastenbefehlen, Erfassen neuer Signale.
Getestet mit Momentum Firmware (mntm-008). Jeder aktuelle Flipper-Fork mit derselben CLI (ir tx, ir rx, storage *, loader *) sollte funktionieren.
v0 Werkzeuge
Werkzeug | Zweck |
| Gibt das |
| Listet |
| Parst eine gespeicherte |
| Sendet eine benannte Taste aus einer gespeicherten |
| Sendet ein ad-hoc geparstes IR-Signal als MSB-First-Integer-Hex (z. B. |
| Listet integrierte Universal-IR-Fernbedienungen auf, die in der Firmware verfügbar sind (AC, TV, Ventilatoren, ...) |
| Listet die Signalnamen für eine integrierte Universalfernbedienung auf |
| Sendet ein benanntes Signal von einer integrierten Universalfernbedienung |
| Versetzt den Flipper in den RX-Modus, erfasst den nächsten Tastendruck der Fernbedienung und hängt ihn an eine |
Related MCP server: Flipper Zero MCP Server
Einrichtung (Windows-Host, WSL2)
1. Flipper-USB in WSL weiterleiten
Installieren Sie usbipd-win unter Windows:
winget install usbipdDann (von der Windows PowerShell aus):
usbipd list # find the Flipper's BUSID
usbipd bind --busid <X-Y> # one-time, admin PowerShell
usbipd attach --wsl --busid <X-Y> # each replug / rebootNach dem attach erscheint der Flipper in WSL als /dev/ttyACM0.
2. Seriellen Zugriff in WSL gewähren
sudo usermod -aG dialout $USERStarten Sie dann WSL neu, damit die Gruppe aktiv wird:
wsl.exe --shutdownÖffnen Sie Ihre Shell erneut. groups sollte nun dialout enthalten.
3. Abhängigkeiten installieren
Vom Repository-Stammverzeichnis aus:
uv sync4. Rauchtest
uv run python scripts/smoketest_readonly.pySie sollten Geräteinformationen, eine Liste der Dateien unter /ext/infrared/ und die geparsten Inhalte jeder .ir-Datei sehen.
Ausführung
MCP stdio (für Claude Code, Cursor usw.):
uv run flipper-mcp-bridgeHTTP REST API (für Home Assistant, curl, Skripte):
uv run flipper-mcp-bridge --http --port 8765Endpunkte:
Methode | Pfad | Body / Query |
|
| — |
|
| — |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Home Assistant Integration
Bereitstellungshinweis: Erreichbarkeit von HA
HA muss per HTTP auf die Bridge zugreifen können. Zwei einfache Setups funktionieren sofort:
Bridge auf demselben Host wie HA ausführen (Pi/NUC/Server mit angeschlossenem Flipper). HA greift auf
http://127.0.0.1:8765zu. Am einfachsten.Bridge auf einem beliebigen Linux-Host im LAN ausführen, der immer eingeschaltet ist. Starten Sie sie mit
--host 0.0.0.0(die CLI gibt eine Warnung aus — es gibt in v1 keine Authentifizierung, führen Sie dies also nur in einem vertrauenswürdigen LAN aus). HA greift aufhttp://HOST:8765zu.
WSL2-Hinweis: WSL2 verwendet NAT — die WSL-IP ist von anderen Hosts im LAN nicht erreichbar. Wenn die Bridge innerhalb von WSL2 ausgeführt wird und HA auf einem anderen Gerät darauf zugreifen soll, ist eine netsh interface portproxy-Portweiterleitung auf dem Windows-Host erforderlich, oder die Bridge muss direkt auf dem Windows-Host ausgeführt werden (Python + pyserial funktionieren unter Windows einwandfrei).
Konfiguration
Fügen Sie dies in die configuration.yaml ein:
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"}'Dann in Automatisierungen oder Skripten:
action:
- service: rest_command.flipper_humidifier_toggleFür eine schalterähnliche Entität verwenden Sie einen RESTful-Schalter, der auf denselben /ir/send-button-Endpunkt zeigt (der Status wird von HA verwaltet, da der Flipper selbst den Gerätestatus nicht offenlegt).
Port-Auswahl
Die Bridge wählt ein serielles Gerät in dieser Prioritätsreihenfolge:
Explizites
port=-Argument (nur Bibliotheksnutzung)FLIPPER_PORT-UmgebungsvariableAutomatische Erkennung: das erste angeschlossene Gerät, dessen USB-Hersteller "Flipper Devices Inc." ist (oder VID:PID
0483:5740)Fallback:
/dev/ttyACM0
Im Normalfall müssen Sie also nichts einstellen. Wenn Sie mehrere CDC-Geräte haben und ein bestimmtes festlegen möchten:
FLIPPER_PORT=/dev/ttyACM1 uv run flipper-mcp-bridgeOder fügen Sie env zum .mcp.json-Servereintrag hinzu.
Registrierung bei Claude Code
Das Repository enthält eine .mcp.json im Stammverzeichnis — Claude Code erkennt diese automatisch, wenn Sie eine Sitzung in diesem Verzeichnis starten (Sie werden beim ersten Start aufgefordert, ihr zu vertrauen). Wenn Sie sie explizit registrieren möchten:
claude mcp add flipper -- uv run --directory "$(pwd)" flipper-mcp-bridgeBekannte Einschränkungen
Erfassungslatenz:
learn_ir_buttonbenötigt einige Sekunden, bevor der Flipper tatsächlich mit dem Zuhören beginnt. Drücken Sie die Fernbedienung einen Moment nach dem Aufruf des Werkzeugs, nicht sofort.Transport: Nur CLI-über-seriell. Protobuf RPC ist noch nicht angebunden. Für IR in menschlichem Tempo in Ordnung; kann für durchsatzsensitive Abläufe überarbeitet werden.
Blockiert durch Vordergrund-Apps: Wenn eine Nicht-CLI-App den Flipper besitzt (z. B. der Nachtisch-Uhr-Bildschirm im Leerlauf), ist IR TX blockiert. Die Bridge versucht bei Konflikten einmal
loader close, aber einige Apps können nur manuell auf dem Gerät beendet werden.Raw-IR-Erfassung nicht unterstützt: Signale mit unbekanntem Protokoll werden noch nicht per
learn_ir_buttonkorrekt verarbeitet.Nur IR: Sub-GHz, NFC, RFID, GPIO, BadUSB — nichts davon ist angebunden.
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