flipper-mcp

Flipper Zero의 WiFi Dev Board v1(ESP32-S2)에서 직접 실행되는 Rust MCP(Model Context Protocol) 서버로, AI 에이전트가 네트워크를 통해 Flipper Zero를 제어할 수 있게 해줍니다.

이게 뭔가요?

이 프로젝트는 MCP 서버를 Flipper 자체에 올립니다. MCP 호환 AI 클라이언트(Claude Desktop, Claude Code 등)라면 무엇이든 연결하여 Flipper의 기능을 도구로 사용할 수 있습니다 — SubGHz, NFC, RFID, IR, GPIO, BadUSB, iButton, 파일 저장소 등.

USB로 연결된 호스트 컴퓨터가 필요한 다른 프로젝트와 달리, flipper-mcp는 Flipper에 부착된 ESP32-S2 WiFi 모듈에서 실행됩니다. Flipper는 독립적이고 네트워크로 접근 가능한 도구가 됩니다.

아키텍처

LOCAL (same network):
  MCP Client ──HTTP──► flipper-mcp.local:8080 (ESP32-S2) ──UART──► Flipper Zero

REMOTE (cross-network):
  MCP Client ──HTTP──► Relay Server ◄──WebSocket── ESP32-S2 ──UART──► Flipper Zero

ESP32-S2는 MCP 프로토콜을 구현하는 HTTP 서버를 실행합니다. MCP 도구 호출을 115200 baud의 UART를 통해 Flipper Zero CLI 명령으로 변환합니다. 컴패니언 릴레이 서버는 모든 네트워크에서 원격 접속을 가능하게 합니다.

기능

• 약 30개의 내장 도구 — 모든 기본 Flipper Zero 애플리케이션을 커버
• 동적 모듈 검색 — SD 카드에서 FAP 앱 자동 감지 + TOML 설정 기반 도구
• Flipper 우선 설정 — Flipper FAP에서 WiFi 구성 (휴대폰, 브라우저, PC 스크립트 불필요)
• 이중 MCP 전송 — Streamable HTTP (최신) + Legacy SSE (하위 호환)
• 로컬 검색 — flipper-mcp.local로 mDNS 광고
• 원격 접속 — 릴레이 서버를 통한 역방향 WebSocket 터널 (포트 포워딩 불필요)
• 인증 없음 — 펜테스팅 및 보안 연구 시나리오를 위해 설계됨
• 컴패니언 릴레이 서버 — 크로스 네트워크 접속을 위한 소형 Rust 바이너리, 여러 Flipper 지원

필요한 하드웨어

• Flipper Zero (CLI를 지원하는 모든 펌웨어 버전)
• WiFi Dev Board v1 (ESP32-S2-WROVER 모듈)

어떤 장치에 연결해야 하나요?

단계	연결 대상	비고
펌웨어 플래싱	WiFi Dev Board USB-C	보드에 Flipper와 별도인 자체 USB 포트가 있음
시리얼 모니터링	WiFi Dev Board USB-C	플래싱과 동일한 USB 연결
SD 카드 설정 파일	Flipper Zero SD 카드	SD를 Flipper에 삽입하거나, 분리하여 PC에 마운트
서버 제어 명령	Flipper Zero SD 카드	apps_data/flipper_mcp/에 server.cmd 파일 생성
UART 통신	자동	WiFi Dev Board와 Flipper는 GPIO 헤더로 연결됨
MCP HTTP 요청	WiFi Dev Board IP:8080	WiFi 네트워크를 통해 연결

사전 요구 사항

• Rust — rustup으로 설치:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  

• Xtensa 툴체인 — ESP32-S2는 커스텀 Rust 툴체인이 필요합니다:

  cargo install espup
  espup install
  source ~/export-esp.sh  # Run this in every new terminal
  

• 플래시 도구 및 링커 프록시:

  cargo install espflash
  cargo install ldproxy
  

• 시스템 패키지 (Debian/Ubuntu/Kali):

  sudo apt install -y git curl gcc build-essential pkg-config libudev-dev libssl-dev python3 python3-venv cmake ninja-build
  

빠른 시작

전체 설정 안내는 docs/SETUP.md를 참조하세요

1. 펌웨어 빌드 및 플래싱

source ~/export-esp.sh
cd firmware
cargo build --release --target xtensa-esp32s2-espidf
espflash flash --monitor target/xtensa-esp32s2-espidf/release/flipper-mcp

3. WiFi 구성

Flipper SD 카드의 SD:/apps_data/flipper_mcp/config.txt에 config.txt를 생성하세요:

wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp

또는 컴패니언 FAP를 사용하여 Flipper에서 직접 구성할 수 있습니다 (5단계 참조): Apps → Tools → Flipper MCP → Configure WiFi

설정 파일 없이 첫 부팅 시, ESP32는 대기하며 상태 파일에 status=needs_config를 기록합니다. Flipper FAP가 Status 화면에 이를 표시합니다.

4. 서버가 작동하는지 확인

AI 클라이언트를 구성하기 전에, curl로 서버에 접근 가능한지 확인하세요:

# Quick health check
curl http://flipper-mcp.local:8080/health

# Full verification — initialize + list all available tools
./scripts/test-connection.sh

# If mDNS isn't resolving on your OS, pass the IP directly:
./scripts/test-connection.sh 192.168.x.xxx

curl로 MCP 도구를 직접 테스트

Flipper MCP → Status 메뉴에서 Flipper의 IP를 확인한 후 테스트하세요:

BLE 비컨 브로드캐스트 (스푸핑된 BLE 광고 전송):

curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ble_beacon","arguments":{"data":"020106"}}}'

BLE HID 키보드 (무선 키보드를 에뮬레이트하고 입력):

# Start HID emulation
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ble_hid_start","arguments":{}}}'

# Type a message
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ble_hid_type","arguments":{"text":"Hello from Flipper!"}}}'

# Stop HID emulation
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ble_hid_stop","arguments":{}}}'

IR 전송 (IR 리모컨 코드 전송):

# NEC protocol IR code (generic TV power button)
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ir_tx","arguments":{"protocol":"NEC","address":"00","command":"01","repeat":0}}}'

SubGHz 수신 (433.92 MHz에서 무선 신호 청취):

curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"subghz_rx","arguments":{"frequency":433920000,"duration":5000}}}'

192.168.0.58을 Flipper의 실제 IP 주소로 바꾸세요.

그런 다음 Claude Desktop 설정(claude_desktop_config.json)에 추가하세요:

{
  "mcpServers": {
    "flipper": {
      "url": "http://flipper-mcp.local:8080/mcp"
    }
  }
}

5. Flipper에서 WiFi 보드 관리

flipper-app/의 컴패니언 Flipper MCP 앱을 Flipper Zero에 설치하세요. ufbt로 빌드하고 .fap을 SD:/apps/Tools/에 복사하세요:

cd flipper-app && ufbt   # produces flipper_mcp.fap
# Copy flipper_mcp.fap to your Flipper SD card under apps/Tools/

앱은 Apps → Tools → Flipper MCP에 나타나며 다음을 제공합니다:

화면	기능
Status	ESP32에 새 상태 업데이트를 요청하고 IP, SSID, 서버 상태, 버전을 표시
Start / Stop / Restart	MCP HTTP 서버 수명 주기를 제어
Reboot Board	ESP32 WiFi Dev Board를 재시작
Configure WiFi	SSID + 비밀번호를 입력하는 온스크린 키보드; SD 카드에 config.txt를 기록
View Logs	ESP32가 30초마다 기록하는 스크롤 가능한 진단 로그
Tools List	ESP32에 현재 등록된 모든 MCP 도구의 스크롤 가능한 목록
Refresh Modules	ESP32에서 FAP 검색 재스캔 + modules.toml 재로드를 트리거

앱은 SD 카드 파일을 통해 통신합니다 (GPIO 헤더 외에 추가 배선 불필요). Configure WiFi는 첫 부팅 마법사입니다 — 휴대폰, 브라우저, PC 스크립트가 필요 없습니다.

6. (선택 사항) 릴레이를 통한 원격 접속

자체 호스팅 (바이너리를 어디서든 실행):

./scripts/build-relay.sh
./target/release/flipper-mcp-relay --listen 0.0.0.0:9090
# Then add relay_url to config.txt on the Flipper SD card:
# relay_url=ws://your-server:9090/tunnel

클라우드 배포 (AWS 또는 GCP, TLS + DNS 포함):

# Bootstrap state storage, then deploy
./infra/bootstrap/aws.sh   # or ./infra/bootstrap/gcp.sh
cd infra/aws && cp terraform.tfvars.example terraform.tfvars
tofu init && tofu apply
# Outputs the relay URL and a ready-to-paste wifi-config.sh command

전체 안내는 RELAY.md를 참조하세요.

사용 가능한 도구

카테고리	도구	설명
SubGHz	subghz_tx, subghz_rx, subghz_decode_raw, subghz_chat, subghz_tx_from_file	무선 주파수 작업
NFC	nfc_detect, nfc_read, nfc_emulate, nfc_field	NFC 태그 상호작용
RFID	rfid_read, rfid_emulate, rfid_write	저주파 RFID
Infrared	ir_tx, ir_rx	IR 리모컨
GPIO	gpio_read, gpio_write, gpio_set_mode	핀 I/O 제어
BadUSB	badusb_run, badusb_list	USB HID 공격
iButton	ibutton_read, ibutton_emulate	1-Wire 키 포브
Storage	storage_list, storage_read, storage_write, storage_remove, storage_stat	SD 카드 파일 관리
System	system_device_info, system_power_info, system_power_reboot, system_ps, system_free, system_uptime	장치 관리
BLE	ble_info, ble_beacon, ble_beacon_stop, ble_hid_start, ble_hid_type, ble_hid_press, ble_hid_mouse, ble_hid_stop	Bluetooth Low Energy (비컨 브로드캐스트 + HID 에뮬레이션)
Apps	app_launch_{name} (SD 카드에서 자동 검색)	애플리케이션 관리