flipper-mcp-bridge
flipper-mcp-bridge
MCP 服务器,将通过 USB 连接的 Flipper Zero 作为 MCP 客户端(如 Claude Code、通过兼容桥接器的 Home Assistant 等)的一组工具。v0 版本专注于红外功能:列出/解析已保存的 .ir 文件、重放按钮、捕获新信号。
已在 Momentum 固件 (mntm-008) 上测试。任何具有相同 CLI (ir tx, ir rx, storage *, loader *) 的近期 Flipper 分支版本均应适用。
v0 工具
工具 | 用途 |
| 返回 Flipper 的 |
| 列出 SD 卡上目录下的 |
| 解析已保存的 |
| 发送来自已保存 |
| 通过 MSB 优先的整数十六进制发送临时解析的红外信号(例如 |
| 列出固件上可用的内置通用红外遥控器(空调、电视、风扇等) |
| 列出内置通用遥控器的信号名称 |
| 发送来自内置通用遥控器的指定信号 |
| 将 Flipper 置于 RX 模式,捕获下一次遥控器按键,并将其附加到 |
Related MCP server: Flipper Zero MCP Server
设置(Windows 主机,WSL2)
1. 将 Flipper USB 转发到 WSL
在 Windows 上安装 usbipd-win:
winget install usbipd然后(从 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 / rebootattach 后,Flipper 将在 WSL 中显示为 /dev/ttyACM0。
2. 在 WSL 中授予串口访问权限
sudo usermod -aG dialout $USER然后重启 WSL 以使组生效:
wsl.exe --shutdown重新打开 shell。groups 现在应该包含 dialout。
3. 安装依赖
从仓库根目录:
uv sync4. 冒烟测试
uv run python scripts/smoketest_readonly.py你应该能看到设备信息、/ext/infrared/ 下的文件列表以及每个 .ir 文件的解析内容。
运行
MCP stdio(用于 Claude Code、Cursor 等):
uv run flipper-mcp-bridgeHTTP REST API(用于 Home Assistant、curl、脚本):
uv run flipper-mcp-bridge --http --port 8765端点:
方法 | 路径 | 正文 / 查询 |
|
| — |
|
| — |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Home Assistant 集成
部署说明:从 HA 可达性
HA 需要能够通过 HTTP 访问该桥接器。两种简单的设置可以直接使用:
在与 HA 相同的主机上运行桥接器(插入 Flipper 的 Pi/NUC/服务器)。HA 访问
http://127.0.0.1:8765。最简单。在局域网内任何常开的 Linux 主机上运行桥接器。使用
--host 0.0.0.0启动(CLI 会打印警告——v1 版本没有身份验证,因此仅在受信任的局域网内执行此操作)。HA 访问http://HOST:8765。
WSL2 注意事项:WSL2 使用 NAT——WSL IP 在局域网的其他主机上不可达。在 WSL2 内运行桥接器并期望不同设备上的 HA 访问它,需要在 Windows 主机上进行 netsh interface portproxy 端口转发,或者直接在 Windows 主机上运行桥接器(Python + pyserial 在 Windows 上运行良好)。
配置
将其放入 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"}'然后在自动化或脚本中:
action:
- service: rest_command.flipper_humidifier_toggle对于类似开关的实体,请使用指向相同 /ir/send-button 端点的 RESTful 开关(状态由 HA 维护,因为 Flipper 本身不暴露设备状态)。
端口选择
桥接器按以下优先级顺序选择串口设备:
显式的
port=参数(仅限库使用)FLIPPER_PORT环境变量自动检测:USB 制造商为 "Flipper Devices Inc."(或 VID:PID
0483:5740)的第一个已连接设备回退:
/dev/ttyACM0
因此在通常情况下,你不需要设置任何内容。如果你有多个 CDC 设备并想固定其中一个:
FLIPPER_PORT=/dev/ttyACM1 uv run flipper-mcp-bridge或者将 env 添加到 .mcp.json 服务器条目中。
在 Claude Code 中注册
该仓库在根目录提供了一个 .mcp.json 文件——当你在此目录中启动会话时,Claude Code 会自动识别它(首次启动时会提示你信任它)。如果你想显式注册它:
claude mcp add flipper -- uv run --directory "$(pwd)" flipper-mcp-bridge已知限制
捕获延迟:
learn_ir_button在 Flipper 真正开始监听之前需要几秒钟。调用工具后稍等片刻再按下遥控器,不要立即按下。传输:仅限串口 CLI。Protobuf RPC 尚未连接。对于人类节奏的红外操作没问题;可能会针对吞吐量敏感的流程重新考虑。
被前台应用阻塞:如果非 CLI 应用拥有 Flipper(例如床头钟空闲屏幕),红外发送将被阻塞。桥接器在冲突时会尝试执行一次
loader close,但某些应用只能在设备上手动退出。不支持原始红外捕获:未知协议信号尚无法通过
learn_ir_button进行往返。仅限红外:Sub-GHz、NFC、RFID、GPIO、BadUSB——这些均未连接。
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