flipper-mcp-bridge
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
Инструмент | Назначение |
| Возвращает словарь |
| Список файлов |
| Анализирует сохраненный файл |
| Передает именованную кнопку из сохраненного файла |
| Передает произвольно проанализированный ИК-сигнал в виде шестнадцатеричного целого числа (старший бит первый, например |
| Список встроенных универсальных ИК-пультов, доступных в прошивке (кондиционеры, ТВ, вентиляторы и т. д.) |
| Список названий сигналов для встроенного универсального пульта |
| Передает именованный сигнал со встроенного универсального пульта |
| Переводит Flipper в режим RX, захватывает следующее нажатие пульта и добавляет его в файл |
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 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 (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 — ничего из этого не подключено.
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