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?

Voraussetzungen

• Rust — Installation über rustup:
  root@kitploit:~

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

• Xtensa-Toolchain — ESP32-S2 erfordert eine benutzerdefinierte Rust-Toolchain:
  root@kitploit:~

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

• Flash-Tool & Linker-Proxy:
  root@kitploit:~

  cargo install espflash
  cargo install ldproxy
  

• Systempakete (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
  

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:

Die App kommuniziert über SD-Kartendateien (keine zusätzliche Verkabelung über den GPIO-Header hinaus). Configure WiFi ist der Erststart-Assistent — kein Telefon, Browser oder PC-Skripte erforderlich.

6. (Optional) Fernzugriff über Relay

Selbst gehostet (die Binary überall ausführen):

./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

Cloud-Bereitstellung (AWS oder GCP, mit 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

Vollständige Anweisungen findest du in RELAY.md.

Verfügbare Tools

Benutzerdefinierte Tools können über TOML-Konfigurationsdateien oder durch Installieren von FAP-Apps auf der SD-Karte hinzugefügt werden. Siehe OPERATIONS.md für Copy-Paste-curl-Befehle für jedes Tool.

Kostenlose Alternative: Open WebUI + Ollama

Du brauchst kein Claude-Abonnement, um flipper-mcp zu nutzen. Open WebUI ist eine kostenlose, selbst gehostete ChatGPT-ähnliche Oberfläche, die MCP Streamable HTTP nativ unterstützt (v0.6.31+). Kombiniere sie mit Ollama für vollständig lokale, offline KI-gesteuerte Flipper-Steuerung.

1. Ollama installieren und ein tool-fähiges Modell herunterladen

# 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 starten

# 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

Öffne http://localhost:3000 in deinem Browser.

3. Den Flipper-MCP-Server verbinden

1. Gehe zu Admin Settings (Zahnrad-Symbol) → External Tools
2. Klicke auf + Add Server
3. Setze Type auf MCP (Streamable HTTP)
4. Gib die Server-URL ein:
   • Lokal: http://flipper-mcp.local:8080/mcp (oder http://192.168.x.x:8080/mcp)
   • Über Relay: https://relay.example.com/mcp
   • Von Docker aus: verwende http://host.docker.internal:8080/mcp, wenn der Flipper im Netzwerk des Docker-Hosts ist
5. Setze Authentication auf None (flipper-mcp hat keine Authentifizierung)
6. Speichern

Tipp: Stelle unter Workspace → Models → (dein Modell) → Advanced Parameters die Function Calling auf Default für kleinere Modelle. Wechsle nur dann zu Native, wenn Modelle eine starke integrierte Tool-Unterstützung haben (Llama 3.1 8B+, Qwen 2.5, Mistral).

4. Beispiel-Prompts

Sobald verbunden, probiere diese im Open WebUI-Chat aus:

Mehrstufige agentische Aufgaben funktionieren am besten mit größeren Modellen (Llama 3.1 70B, Qwen 2.5 72B oder Cloud-Modelle über OpenAI-kompatible APIs). Kleinere Modelle bewältigen Einzel-Tool-Aufrufe zuverlässig.

Projektstruktur

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

Dokumentation

• SETUP.md — Vollständige Einrichtung von Grund auf
• ARCHITECTURE.md — Detaillierter Einblick in das Systemdesign
• API.md — Vollständige MCP-Tool-Referenz
• OPERATIONS.md — Betriebshandbuch mit curl-Befehlen für jedes Tool
• MODULE_DEVELOPMENT.md — Benutzerdefinierte Module erstellen
• RELAY.md — Einrichtung des Fernzugriffs
• HARDWARE.md — Verkabelung und Hardware-Details
• TROUBLESHOOTING.md — Häufige Probleme und Lösungen
• DESIGN.md — Technisches Design und Systemarchitektur

Für KI-Agenten

Siehe AGENTS.md für vollständigen Projektkontext, technische Spezifikationen, Systemarchitektur und alles, was für die Weiterentwicklung dieses Projekts benötigt wird.

Lizenz

MIT