flipper-mcp-bridge
flipper-mcp-bridge
USB로 연결된 Flipper Zero를 MCP 클라이언트(Claude Code, 호환 브리지를 통한 Home Assistant 등)를 위한 도구 세트로 노출하는 MCP 서버입니다. v0 버전은 IR에 중점을 둡니다: 저장된 .ir 파일 나열/파싱, 버튼 재전송, 새로운 신호 캡처.
**Momentum 펌웨어(mntm-008)**에서 테스트되었습니다. 동일한 CLI(ir tx, ir rx, storage *, loader *)를 사용하는 최신 Flipper 포크라면 모두 작동할 것입니다.
v0 도구
도구 | 목적 |
| Flipper의 |
| SD 카드의 디렉터리에 있는 |
| 저장된 |
| 저장된 |
| MSB 우선 정수 16진수(예: |
| 펌웨어에서 사용 가능한 내장 범용 IR 리모컨 나열(ac, tv, fans 등) |
| 내장 범용 리모컨의 신호 이름 나열 |
| 내장 범용 리모컨에서 지정된 신호 전송 |
| Flipper를 RX 모드로 전환하여 다음 리모컨 입력을 캡처하고 |
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 / rebootattach 후, 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와 동일한 호스트에서 브리지 실행 (Flipper가 연결된 Pi/NUC/서버). HA는
http://127.0.0.1:8765에 접속합니다. 가장 간단합니다.LAN의 항상 켜져 있는 Linux 호스트에서 브리지 실행.
--host 0.0.0.0으로 시작합니다 (CLI가 경고를 출력합니다 — v1에는 인증이 없으므로 신뢰할 수 있는 LAN에서만 수행하십시오). HA는http://HOST:8765에 접속합니다.
WSL2 주의사항: WSL2는 NAT를 사용하므로 WSL IP는 LAN의 다른 호스트에서 접근할 수 없습니다. 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 스위치를 사용하십시오(Flipper 자체가 장치 상태를 노출하지 않으므로 상태는 HA에 의해 유지됩니다).
포트 선택
브리지는 다음 우선순위에 따라 시리얼 장치를 선택합니다:
명시적
port=인수 (라이브러리 사용 시만)FLIPPER_PORT환경 변수자동 감지: USB 제조업체가 "Flipper Devices Inc."인 첫 번째 연결된 장치 (또는 VID:PID
0483:5740)대체:
/dev/ttyACM0
따라서 일반적인 경우에는 아무것도 설정할 필요가 없습니다. 여러 CDC 장치가 있고 특정 장치를 고정하려면:
FLIPPER_PORT=/dev/ttyACM1 uv run flipper-mcp-bridge또는 .mcp.json 서버 항목에 env를 추가하십시오.
Claude Code에 등록
저장소 루트에 .mcp.json이 포함되어 있습니다. 이 디렉터리에서 세션을 시작하면 Claude Code가 자동으로 이를 감지합니다(첫 실행 시 신뢰 여부를 묻는 메시지가 표시됩니다). 명시적으로 등록하려면:
claude mcp add flipper -- uv run --directory "$(pwd)" flipper-mcp-bridge알려진 제한 사항
캡처 지연:
learn_ir_button은 Flipper가 실제로 수신을 시작하기까지 몇 초가 걸립니다. 도구를 호출한 직후가 아니라 잠시 후에 리모컨을 누르십시오.전송: 시리얼을 통한 CLI만 지원합니다. Protobuf RPC는 아직 연결되지 않았습니다. 사람이 사용하는 속도의 IR에는 적합하지만, 처리량이 중요한 흐름에 대해서는 나중에 다시 검토될 수 있습니다.
포그라운드 앱에 의한 차단: CLI가 아닌 앱이 Flipper를 소유하고 있는 경우(예: 탁상 시계 대기 화면), IR TX가 차단됩니다. 브리지는 충돌 시
loader close를 한 번 시도하지만, 일부 앱은 장치에서 수동으로 종료해야만 합니다.Raw IR 캡처 미지원: 알 수 없는 프로토콜 신호는 아직
learn_ir_button을 통해 왕복할 수 없습니다.IR 전용: 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