flipper-mcp-bridge
Provides HTTP REST API endpoints for Home Assistant automation, allowing control of infrared devices via REST commands and switches integrated with Flipper Zero IR capabilities.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@flipper-mcp-bridge turn off the air conditioner"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Return the Flipper's |
| List |
| Parse a saved |
| Transmit a named button from a saved |
| Transmit an ad-hoc parsed IR signal by MSB-first integer hex (e.g. |
| List built-in universal IR remotes available on the firmware (ac, tv, fans, ...) |
| List the signal names for a built-in universal remote |
| Transmit a named signal from a built-in universal remote |
| Put the Flipper in RX, capture the next remote press, append it to a |
Related MCP server: Flipper Zero MCP Server
Setup (Windows host, WSL2)
1. Forward the Flipper USB into WSL
Install usbipd-win on Windows:
winget install usbipdThen (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 / rebootAfter attach, the Flipper shows up in WSL as /dev/ttyACM0.
2. Grant serial access in WSL
sudo usermod -aG dialout $USERThen restart WSL so the group is active:
wsl.exe --shutdownReopen your shell. groups should now include dialout.
3. Install dependencies
From the repo root:
uv sync4. Smoke test
uv run python scripts/smoketest_readonly.pyYou 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-bridgeHTTP REST API (for Home Assistant, curl, scripts):
uv run flipper-mcp-bridge --http --port 8765Endpoints:
Method | Path | Body / Query |
|
| — |
|
| — |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
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.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 hitshttp://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_toggleFor 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:
Explicit
port=argument (library use only)FLIPPER_PORTenvironment variableAuto-detect: the first attached device whose USB manufacturer is "Flipper Devices Inc." (or VID:PID
0483:5740)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-bridgeOr 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-bridgeKnown limitations
Capture latency:
learn_ir_buttontakes 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 closeonce 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_buttonyet.IR only: Sub-GHz, NFC, RFID, GPIO, BadUSB — none of these are wired.
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