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 工具

工具	用途
`device_info`	返回 Flipper 的 `device_info` 字典（固件、硬件、无线电）
`list_ir_files`	列出 SD 卡上目录下的 `.ir` 文件
`list_ir_buttons`	解析已保存的 `.ir` 文件并返回其按钮
`send_ir_button`	发送来自已保存 `.ir` 文件的指定按钮
`send_ir_signal`	通过 MSB 优先的整数十六进制发送临时解析的红外信号（例如 `NECext DF02 EE11`）
`list_universal_remotes`	列出固件上可用的内置通用红外遥控器（空调、电视、风扇等）
`list_universal_signals`	列出内置通用遥控器的信号名称
`send_universal_signal`	发送来自内置通用遥控器的指定信号
`learn_ir_button`	将 Flipper 置于 RX 模式，捕获下一次遥控器按键，并将其附加到 `.ir` 文件

设置（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 / reboot

attach 后，Flipper 将在 WSL 中显示为 /dev/ttyACM0。

2. 在 WSL 中授予串口访问权限

sudo usermod -aG dialout $USER

然后重启 WSL 以使组生效：

wsl.exe --shutdown

重新打开 shell。groups 现在应该包含 dialout。

3. 安装依赖

从仓库根目录：

uv sync

4. 冒烟测试

uv run python scripts/smoketest_readonly.py

你应该能看到设备信息、/ext/infrared/ 下的文件列表以及每个 .ir 文件的解析内容。

运行

MCP stdio（用于 Claude Code、Cursor 等）：

uv run flipper-mcp-bridge

HTTP REST API（用于 Home Assistant、curl、脚本）：

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

端点：

方法	路径	正文 / 查询
`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`（省略以列出可用遥控器）
`POST`	`/ir/universal/send`	`{"remote": "ac", "signal": "OFF"}`
`POST`	`/ir/learn`	`{"file": "...", "button": "...", "timeout_seconds": 30}`

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——这些均未连接。