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
`device_info`	Gibt das `device_info`-Dictionary des Flippers zurück (Firmware, Hardware, Funk)
`list_ir_files`	Listet `.ir`-Dateien in einem Verzeichnis auf der SD-Karte auf
`list_ir_buttons`	Parst eine gespeicherte `.ir`-Datei und gibt deren Tasten zurück
`send_ir_button`	Sendet eine benannte Taste aus einer gespeicherten `.ir`-Datei
`send_ir_signal`	Sendet ein ad-hoc geparstes IR-Signal als MSB-First-Integer-Hex (z. B. `NECext DF02 EE11`)
`list_universal_remotes`	Listet integrierte Universal-IR-Fernbedienungen auf, die in der Firmware verfügbar sind (AC, TV, Ventilatoren, ...)
`list_universal_signals`	Listet die Signalnamen für eine integrierte Universalfernbedienung auf
`send_universal_signal`	Sendet ein benanntes Signal von einer integrierten Universalfernbedienung
`learn_ir_button`	Versetzt den Flipper in den RX-Modus, erfasst den nächsten Tastendruck der Fernbedienung und hängt ihn an eine `.ir`-Datei an

Einrichtung (Windows-Host, WSL2)

1. Flipper-USB in WSL weiterleiten

Installieren Sie usbipd-win unter Windows:

winget install usbipd

Dann (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 / reboot

Nach dem attach erscheint der Flipper in WSL als /dev/ttyACM0.

2. Seriellen Zugriff in WSL gewähren

sudo usermod -aG dialout $USER

Starten 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 sync

4. Rauchtest

uv run python scripts/smoketest_readonly.py

Sie 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-bridge

HTTP REST API (für Home Assistant, curl, Skripte):

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

Endpunkte:

Methode	Pfad	Body / Query
`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` (weglassen, um verfügbare Fernbedienungen aufzulisten)
`POST`	`/ir/universal/send`	`{"remote": "ac", "signal": "OFF"}`
`POST`	`/ir/learn`	`{"file": "...", "button": "...", "timeout_seconds": 30}`

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:8765 zu. 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 auf http://HOST:8765 zu.

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_toggle

Fü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-Umgebungsvariable
Automatische 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-bridge

Oder 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-bridge

Bekannte Einschränkungen

Erfassungslatenz: learn_ir_button benö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_button korrekt verarbeitet.
Nur IR: Sub-GHz, NFC, RFID, GPIO, BadUSB — nichts davon ist angebunden.