Skip to main content
Glama
flipper-mcp-bridge

flipper-mcp-bridge

by dudebot

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 文件

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 / 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 访问该桥接器。两种简单的设置可以直接使用:

  1. 在与 HA 相同的主机上运行桥接器(插入 Flipper 的 Pi/NUC/服务器)。HA 访问 http://127.0.0.1:8765。最简单。

  2. 在局域网内任何常开的 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 本身不暴露设备状态)。

端口选择

桥接器按以下优先级顺序选择串口设备:

  1. 显式的 port= 参数(仅限库使用)

  2. FLIPPER_PORT 环境变量

  3. 自动检测:USB 制造商为 "Flipper Devices Inc."(或 VID:PID 0483:5740)的第一个已连接设备

  4. 回退:/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 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