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` 파일에 추가

설정 (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로 연결할 수 있어야 합니다. 두 가지 쉬운 설정이 바로 작동합니다:

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는 연결되어 있지 않습니다.