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`

Настройка (хост 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-запросы к мосту. Два простых варианта работают «из коробки»:

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

Выбор порта

Мост выбирает последовательное устройство в следующем порядке приоритета:

Явный аргумент 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 еще не подключен. Это подходит для ИК-команд с человеческой скоростью; может быть пересмотрено для потоков, чувствительных к пропускной способности.
Блокировка фоновыми приложениями: если Flipper занят приложением, не являющимся CLI (например, экран ожидания «Прикроватные часы»), передача ИК-сигнала блокируется. Мост пытается выполнить loader close при конфликте, но некоторые приложения можно закрыть только вручную на устройстве.
Захват «сырого» ИК-сигнала не поддерживается: сигналы неизвестных протоколов пока не будут корректно обрабатываться через learn_ir_button.
Только ИК: Sub-GHz, NFC, RFID, GPIO, BadUSB — ничего из этого не подключено.