flipper-mcp

Ein Rust-MCP-Server (Model Context Protocol), der direkt auf dem WiFi Dev Board v1 (ESP32-S2) des Flipper Zero läuft und es KI-Agenten ermöglicht, einen Flipper Zero über das Netzwerk zu steuern.

Was ist das?

Dieses Projekt platziert einen MCP-Server auf dem Flipper selbst. Jeder MCP-kompatible KI-Client (Claude Desktop, Claude Code usw.) kann sich verbinden und die Fähigkeiten des Flipper als Tools nutzen — SubGHz, NFC, RFID, IR, GPIO, BadUSB, iButton, Dateispeicher und mehr.

Anders als andere Projekte, die einen USB-verbundenen Host-Computer erfordern, läuft flipper-mcp auf dem ESP32-S2-WiFi-Modul, das am Flipper angebracht ist. Der Flipper wird zu einem eigenständigen, netzwerkzugänglichen Werkzeug.

Architektur

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

Der ESP32-S2 betreibt einen HTTP-Server, der das MCP-Protokoll implementiert. Er übersetzt MCP-Tool-Aufrufe in Flipper Zero CLI-Befehle über UART mit 115200 Baud. Ein begleitender Relay-Server ermöglicht den Fernzugriff aus jedem Netzwerk.

Funktionen

• ~30 integrierte Tools, die alle Standard-Flipper-Zero-Anwendungen abdecken
• Dynamische Modulerkennung — automatische Erkennung von FAP-Apps von der SD-Karte + TOML-konfigurationsgesteuerte Tools
• Flipper-First-Einrichtung — WiFi über die Flipper-FAP konfigurieren (kein Telefon, Browser oder PC-Skripte erforderlich)
• Dualer MCP-Transport — Streamable HTTP (modern) + Legacy SSE (abwärtskompatibel)
• Lokale Erkennung — mDNS-Ankündigung als flipper-mcp.local
• Fernzugriff — Reverse-WebSocket-Tunnel über einen Relay-Server (keine Portweiterleitung erforderlich)
• Keine Authentifizierung — konzipiert für Pentesting- und Sicherheitsforschungsszenarien
• Begleitender Relay-Server — kleine Rust-Binary für netzwerkübergreifenden Zugriff, unterstützt mehrere Flipper

Erforderliche Hardware

• Flipper Zero (jede Firmware-Version mit CLI-Unterstützung)
• WiFi Dev Board v1 (ESP32-S2-WROVER-Modul)

Mit welchem Gerät verbinde ich mich?

Stage	Connect to	Notes
Flashing firmware	WiFi Dev Board USB-C	Board has its own USB port, separate from Flipper
Serial monitoring	WiFi Dev Board USB-C	Same USB connection as flashing
SD card config files	Flipper Zero SD card	Insert SD into Flipper, or remove and mount on PC
Server control commands	Flipper Zero SD card	Create server.cmd file in apps_data/flipper_mcp/
UART communication	Automatic	WiFi Dev Board and Flipper connect via GPIO header
MCP HTTP requests	WiFi Dev Board IP:8080	Connect over your WiFi network

Voraussetzungen

• Rust — Installation über rustup:

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

• Xtensa-Toolchain — ESP32-S2 erfordert eine benutzerdefinierte Rust-Toolchain:

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

• Flash-Tool & Linker-Proxy:

  cargo install espflash
  cargo install ldproxy
  

• Systempakete (Debian/Ubuntu/Kali):

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

Schnellstart

Vollständige Einrichtungsanleitung in docs/SETUP.md

1. Firmware bauen & flashen

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 konfigurieren

Erstelle config.txt auf der Flipper-SD-Karte unter SD:/apps_data/flipper_mcp/config.txt:

wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp

Oder direkt vom Flipper aus konfigurieren mit der begleitenden FAP (siehe Schritt 5): Apps → Tools → Flipper MCP → Configure WiFi

Beim ersten Start ohne Konfigurationsdatei wartet der ESP32 und schreibt status=needs_config in die Statusdatei. Die Flipper-FAP zeigt dies auf dem Status-Bildschirm an.

4. Überprüfen, ob der Server funktioniert

Bevor du einen KI-Client konfigurierst, bestätige mit curl, dass der Server erreichbar ist:

# 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

MCP-Tools direkt mit curl testen

Hole die IP des Flipper aus dem Menü Flipper MCP → Status und teste dann:

BLE-Beacon-Broadcast (gefoppte BLE-Werbung senden):

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-Tastatur (eine drahtlose Tastatur emulieren und tippen):

# 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-Senden (IR-Fernbedienungscodes senden):

# 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-Empfang (auf Funksignale bei 433,92 MHz hören):

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}}}'

Ersetze 192.168.0.58 durch die tatsächliche IP-Adresse deines Flipper.

Füge dann Folgendes zu deiner Claude-Desktop-Konfiguration (claude_desktop_config.json) hinzu:

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

5. Das WiFi-Board vom Flipper aus verwalten

Installiere die begleitende Flipper MCP-App aus flipper-app/ auf dem Flipper Zero. Baue sie mit ufbt und kopiere die .fap nach SD:/apps/Tools/:

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

Die App erscheint unter Apps → Tools → Flipper MCP und bietet:

Screen	What it does
Status	Requests a fresh status update from the ESP32, shows IP, SSID, server state, version
Start / Stop / Restart	Controls the MCP HTTP server lifecycle
Reboot Board	Restarts the ESP32 WiFi Dev Board
Configure WiFi	On-screen keyboard to enter SSID + password; writes config.txt to SD card
View Logs	Scrollable diagnostic log written by the ESP32 every 30 s
Tools List	Scrollable list of all MCP tools currently registered on the ESP32
Refresh Modules	Triggers FAP discovery rescan + modules.toml reload on the ESP32