Skip to main content
Glama
flipper-mcp-bridge

flipper-mcp-bridge

by dudebot

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

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

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

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

  1. Explizites port=-Argument (nur Bibliotheksnutzung)

  2. FLIPPER_PORT-Umgebungsvariable

  3. Automatische Erkennung: das erste angeschlossene Gerät, dessen USB-Hersteller "Flipper Devices Inc." ist (oder VID:PID 0483:5740)

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

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