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). Любой актуальный форк Flipper с тем же CLI (ir tx, ir rx, storage *, loader *) должен работать.

Инструменты v0

Инструмент

Назначение

device_info

Возвращает словарь device_info Flipper (прошивка, оборудование, радио)

list_ir_files

Список файлов .ir в директории на SD-карте

list_ir_buttons

Анализирует сохраненный файл .ir и возвращает его кнопки

send_ir_button

Передает именованную кнопку из сохраненного файла .ir

send_ir_signal

Передает произвольно проанализированный ИК-сигнал в виде шестнадцатеричного целого числа (старший бит первый, например 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. Проброс USB-устройства Flipper в WSL

Установите usbipd-win в Windows:

winget install usbipd

Затем (из PowerShell в Windows):

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

Переоткройте оболочку. В выводе 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 (Pi/NUC/сервер с подключенным Flipper). HA обращается к http://127.0.0.1:8765. Самый простой способ.

  2. Запуск моста на любом постоянно включенном хосте Linux в локальной сети. Запустите его с параметром --host 0.0.0.0 (CLI выведет предупреждение — в v1 нет аутентификации, поэтому делайте это только в доверенной локальной сети). HA обращается к http://HOST:8765.

Оговорка по WSL2: WSL2 использует NAT — IP-адрес WSL недоступен с других хостов в локальной сети. Запуск моста внутри WSL2 с ожиданием доступа к нему из HA на другом устройстве требует проброса портов netsh interface portproxy на хосте Windows или запуска моста непосредственно на хосте 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

Для сущности типа переключателя используйте RESTful switch, указывающий на тот же эндпоинт /ir/send-button (состояние поддерживается 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 еще не подключен. Это подходит для ИК-команд с человеческой скоростью; может быть пересмотрено для потоков, чувствительных к пропускной способности.

  • Блокировка фоновыми приложениями: если Flipper занят приложением, не являющимся CLI (например, экран ожидания «Прикроватные часы»), передача ИК-сигнала блокируется. Мост пытается выполнить 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