flipper-mcp-bridge

MCP server that exposes a USB-connected Flipper Zero as a set of tools for MCP clients (Claude Code, Home Assistant via compatible bridge, etc.). v0 focuses on IR: list/parse saved .ir files, replay buttons, capture new signals.

Tested against Momentum firmware (mntm-008). Any recent Flipper fork with the same CLI (ir tx, ir rx, storage *, loader *) should work.

v0 tools

Tool	Purpose
device_info	Return the Flipper's device_info dict (firmware, hardware, radio)
list_ir_files	List .ir files under a directory on the SD card
list_ir_buttons	Parse a saved .ir file and return its buttons
send_ir_button	Transmit a named button from a saved .ir file
send_ir_signal	Transmit an ad-hoc parsed IR signal by MSB-first integer hex (e.g. NECext DF02 EE11)
list_universal_remotes	List built-in universal IR remotes available on the firmware (ac, tv, fans, ...)
list_universal_signals	List the signal names for a built-in universal remote
send_universal_signal	Transmit a named signal from a built-in universal remote
learn_ir_button	Put the Flipper in RX, capture the next remote press, append it to a .ir file

Setup (Windows host, WSL2)

1. Forward the Flipper USB into WSL

Install usbipd-win on Windows:

winget install usbipd

Then (from 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

After attach, the Flipper shows up in WSL as /dev/ttyACM0.

2. Grant serial access in WSL

sudo usermod -aG dialout $USER

Then restart WSL so the group is active:

wsl.exe --shutdown

Reopen your shell. groups should now include dialout.

3. Install dependencies

From the repo root:

uv sync

4. Smoke test

uv run python scripts/smoketest_readonly.py

You should see device info, a list of files under /ext/infrared/, and parsed contents of each .ir file.

Running

MCP stdio (for Claude Code, Cursor, etc.):

uv run flipper-mcp-bridge

HTTP REST API (for Home Assistant, curl, scripts):

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

Endpoints:

Method	Path	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 (omit to list available remotes)
POST	/ir/universal/send	{"remote": "ac", "signal": "OFF"}
POST	/ir/learn	{"file": "...", "button": "...", "timeout_seconds": 30}

Home Assistant integration

Deployment note: reachability from HA

HA needs to be able to HTTP to the bridge. Two easy setups work out of the box:

1. Run the bridge on the same host as HA (Pi/NUC/server with Flipper plugged in). HA hits http://127.0.0.1:8765. Simplest.
2. Run the bridge on any always-on Linux host on the LAN. Start it with --host 0.0.0.0 (the CLI prints a warning — there's no auth in v1, so only do this on a trusted LAN). HA hits http://HOST:8765.

WSL2 caveat: WSL2 uses NAT — the WSL IP isn't reachable from other hosts on the LAN. Running the bridge inside WSL2 and expecting HA on a different device to reach it requires netsh interface portproxy port-forwarding on the Windows host, or running the bridge on the Windows host directly (Python + pyserial work fine on Windows).

Configuration

Drop this into 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"}'

Then in automations or scripts:

action:
  - service: rest_command.flipper_humidifier_toggle

For a switch-like entity, use a RESTful switch pointed at the same /ir/send-button endpoint (state is maintained by HA since the Flipper itself doesn't expose device state).

Port selection

The bridge picks a serial device in this priority order:

1. Explicit port= argument (library use only)
2. FLIPPER_PORT environment variable
3. Auto-detect: the first attached device whose USB manufacturer is "Flipper Devices Inc." (or VID:PID 0483:5740)
4. Fallback: /dev/ttyACM0

So in the common case you don't need to set anything. If you've got multiple CDC devices and want to pin a specific one:

FLIPPER_PORT=/dev/ttyACM1 uv run flipper-mcp-bridge

Or add env to the .mcp.json server entry.

Registering with Claude Code

The repo ships a .mcp.json at the root — Claude Code picks it up automatically when you start a session in this directory (you'll be prompted to trust it on first launch). If you'd rather register it explicitly:

claude mcp add flipper -- uv run --directory "$(pwd)" flipper-mcp-bridge

Known limitations

• Capture latency: learn_ir_button takes a few seconds before the Flipper actually starts listening. Press the remote a beat after calling the tool, not immediately.
• Transport: CLI-over-serial only. Protobuf RPC is not wired yet. Fine for IR at human pace; may be revisited for throughput-sensitive flows.
• Blocked by foreground apps: if a non-CLI app owns the Flipper (e.g. the Nightstand Clock idle screen), IR TX is blocked. The bridge tries loader close once on conflict, but some apps can only be exited manually on the device.
• Raw IR capture not supported: unknown-protocol signals won't round-trip via learn_ir_button yet.
• IR only: Sub-GHz, NFC, RFID, GPIO, BadUSB — none of these are wired.