Skip to main content
Glama
flipper-mcp-bridge

flipper-mcp-bridge

by dudebot

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 도구

도구

목적

device_info

Flipper의 device_info 딕셔너리(펌웨어, 하드웨어, 라디오) 반환

list_ir_files

SD 카드의 디렉터리에 있는 .ir 파일 나열

list_ir_buttons

저장된 .ir 파일을 파싱하여 버튼 반환

send_ir_button

저장된 .ir 파일에서 지정된 버튼 전송

send_ir_signal

MSB 우선 정수 16진수(예: NECext DF02 EE11)로 임의 파싱된 IR 신호 전송

list_universal_remotes

펌웨어에서 사용 가능한 내장 범용 IR 리모컨 나열(ac, tv, fans 등)

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

셸을 다시 엽니다. 이제 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. 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에 의해 유지됩니다).

포트 선택

브리지는 다음 우선순위에 따라 시리얼 장치를 선택합니다:

  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

또는 .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 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