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 모듈)

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

사전 요구 사항

• Rust — rustup으로 설치:
  root@kitploit:~

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

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

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

• 플래시 도구 및 링커 프록시:
  root@kitploit:~

  cargo install espflash
  cargo install ldproxy
  

• 시스템 패키지 (Debian/Ubuntu/Kali):
  root@kitploit:~

  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에 나타나며 다음을 제공합니다:

앱은 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를 참조하세요.

사용 가능한 도구

커스텀 도구는 TOML 설정 파일을 통해 또는 SD 카드에 FAP 앱을 설치하여 추가할 수 있습니다. 모든 도구에 대한 복사-붙여넣기 curl 명령은 OPERATIONS.md를 참조하세요.

무료 대안: Open WebUI + Ollama

flipper-mcp를 사용하는 데 Claude 구독이 필요하지 않습니다. Open WebUI는 MCP Streamable HTTP(v0.6.31+)를 기본 지원하는 무료 자체 호스팅 ChatGPT 스타일 인터페이스입니다. Ollama와 함께 사용하면 완전히 로컬에서 오프라인으로 AI 기반 Flipper 제어가 가능합니다.

1. Ollama 설치 및 도구 지원 모델 가져오기

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model with tool-calling support
ollama pull llama3.1        # 8B — good balance of speed and capability
# or: ollama pull qwen2.5   # strong tool-calling, good at structured output
# or: ollama pull mistral    # lightweight, fast tool use

2. Open WebUI 시작

# Docker (recommended) — connects to Ollama on localhost automatically
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -e WEBUI_AUTH=False \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

# Or without Docker:
pip install open-webui
open-webui serve

브라우저에서 **http://localhost:3000**을 여세요.

3. Flipper MCP 서버 연결

1. Admin Settings (기어 아이콘) → External Tools로 이동
2. + Add Server 클릭
3. Type을 **MCP (Streamable HTTP)**로 설정
4. 서버 URL 입력:
   • 로컬: http://flipper-mcp.local:8080/mcp (또는 http://192.168.x.x:8080/mcp)
   • 릴레이 경유: https://relay.example.com/mcp
   • Docker에서: Flipper가 Docker 호스트의 네트워크에 있다면 http://host.docker.internal:8080/mcp 사용
5. Authentication을 None으로 설정 (flipper-mcp에는 인증이 없음)
6. Save

팁: Workspace → Models → (사용 중인 모델) → Advanced Parameters에서 더 작은 모델의 경우 Function Calling을 Default로 설정하세요. 강력한 내장 도구 지원이 있는 모델(Llama 3.1 8B+, Qwen 2.5, Mistral)에만 Native로 전환하세요.

4. 예시 프롬프트

연결되면 Open WebUI 채팅에서 다음을 시도해 보세요:

다단계 에이전트 작업은 더 큰 모델(Llama 3.1 70B, Qwen 2.5 72B, 또는 OpenAI 호환 API를 통한 클라우드 모델)에서 가장 잘 작동합니다. 더 작은 모델은 단일 도구 호출을 안정적으로 처리합니다.

프로젝트 구조

flipper-mcp/
├── firmware/          # ESP32-S2 firmware (Rust, esp-idf-svc)
├── relay/             # Companion relay server (Rust, tokio/axum)
├── flipper-app/       # Flipper Zero FAP — in-device management UI (C, ufbt)
├── infra/             # OpenTofu IaC — cloud relay deployment (AWS + GCP)
├── config/            # Example module configurations
├── scripts/           # Build, flash, and setup helper scripts
└── docs/              # Architecture, setup, API, troubleshooting

문서

• SETUP.md — 처음부터 전체 설정
• ARCHITECTURE.md — 시스템 설계 심층 분석
• API.md — 완전한 MCP 도구 레퍼런스
• OPERATIONS.md — 모든 도구에 대한 curl 명령이 포함된 운영 가이드
• MODULE_DEVELOPMENT.md — 커스텀 모듈 생성
• RELAY.md — 원격 접속 설정
• HARDWARE.md — 배선 및 하드웨어 세부 사항
• TROUBLESHOOTING.md — 일반적인 문제 및 해결 방법
• DESIGN.md — 기술 설계 및 시스템 아키텍처

AI 에이전트용

완전한 프로젝트 컨텍스트, 기술 사양, 시스템 아키텍처, 그리고 이 프로젝트의 개발을 계속하는 데 필요한 모든 것은 AGENTS.md를 참조하세요.

라이선스

MIT