flipper-mcp

Un serveur MCP (Model Context Protocol) en Rust qui s'exécute directement sur la WiFi Dev Board v1 (ESP32-S2) du Flipper Zero, permettant à des agents IA de contrôler un Flipper Zero sur le réseau.

Qu'est-ce que c'est ?

Ce projet place un serveur MCP sur le Flipper lui-même. Tout client IA compatible MCP (Claude Desktop, Claude Code, etc.) peut se connecter et utiliser les capacités du Flipper comme outils — SubGHz, NFC, RFID, IR, GPIO, BadUSB, iButton, stockage de fichiers, et plus encore.

Contrairement à d'autres projets qui nécessitent un ordinateur hôte connecté en USB, flipper-mcp s'exécute sur le module WiFi ESP32-S2 attaché au Flipper. Le Flipper devient un outil autonome, accessible sur le réseau.

Architecture

LOCAL (même réseau) :
  Client MCP ──HTTP──► flipper-mcp.local:8080 (ESP32-S2) ──UART──► Flipper Zero

DISTANT (inter-réseaux) :
  Client MCP ──HTTP──► Serveur relais ◄──WebSocket── ESP32-S2 ──UART──► Flipper Zero

L'ESP32-S2 exécute un serveur HTTP implémentant le protocole MCP. Il traduit les appels d'outils MCP en commandes CLI du Flipper Zero via UART à 115200 bauds. Un serveur relais compagnon permet l'accès distant depuis n'importe quel réseau.

Fonctionnalités

• ~30 outils intégrés couvrant toutes les applications par défaut du Flipper Zero
• Découverte dynamique de modules — détection automatique des applications FAP depuis la carte SD + outils pilotés par configuration TOML
• Configuration Flipper-first — configurez le WiFi depuis le FAP du Flipper (aucun téléphone, navigateur ou script PC nécessaire)
• Double transport MCP — Streamable HTTP (moderne) + Legacy SSE (rétrocompatible)
• Découverte locale — annonce mDNS sous flipper-mcp.local
• Accès distant — tunnel WebSocket inverse via un serveur relais (aucune redirection de port nécessaire)
• Aucune authentification — conçu pour des scénarios de pentesting et de recherche en sécurité
• Serveur relais compagnon — petit binaire Rust pour l'accès inter-réseaux, prend en charge plusieurs Flippers

Matériel requis

• Flipper Zero (toute version de firmware avec support CLI)
• WiFi Dev Board v1 (module ESP32-S2-WROVER)

À quel appareil dois-je me connecter ?

Étape	Se connecter à	Remarques
Flash du firmware	USB-C de la WiFi Dev Board	La carte possède son propre port USB, distinct du Flipper
Surveillance série	USB-C de la WiFi Dev Board	Même connexion USB que le flash
Fichiers de configuration sur carte SD	Carte SD du Flipper Zero	Insérez la SD dans le Flipper, ou retirez-la et montez-la sur le PC
Commandes de contrôle du serveur	Carte SD du Flipper Zero	Créez le fichier server.cmd dans apps_data/flipper_mcp/
Communication UART	Automatique	La WiFi Dev Board et le Flipper se connectent via le connecteur GPIO
Requêtes HTTP MCP	IP de la WiFi Dev Board:8080	Connectez-vous via votre réseau WiFi

Prérequis

• Rust — installez via rustup :

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

• Chaîne d'outils Xtensa — l'ESP32-S2 nécessite une chaîne d'outils Rust personnalisée :

  cargo install espup
  espup install
  source ~/export-esp.sh  # Exécutez ceci dans chaque nouveau terminal
  

• Outil de flash & proxy de linker :

  cargo install espflash
  cargo install ldproxy
  

• Paquets système (Debian/Ubuntu/Kali) :

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

Démarrage rapide

Instructions d'installation complètes dans docs/SETUP.md

1. Compiler & flasher le firmware

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

3. Configurer le WiFi

Créez config.txt sur la carte SD du Flipper à l'emplacement SD:/apps_data/flipper_mcp/config.txt :

wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp

Ou configurez directement depuis le Flipper à l'aide du FAP compagnon (voir Étape 5) : Apps → Tools → Flipper MCP → Configure WiFi

Au premier démarrage sans fichier de configuration, l'ESP32 attend et écrit status=needs_config dans le fichier de statut. Le FAP du Flipper affichera cela sur l'écran Status.

4. Vérifier que le serveur fonctionne

Avant de configurer un client IA, confirmez que le serveur est joignable avec curl :

# Vérification rapide de l'état
curl http://flipper-mcp.local:8080/health

# Vérification complète — initialisation + liste de tous les outils disponibles
./scripts/test-connection.sh

# Si mDNS ne se résout pas sur votre OS, passez l'IP directement :
./scripts/test-connection.sh 192.168.x.xxx

Tester les outils MCP directement avec curl

Récupérez l'IP du Flipper depuis le menu Flipper MCP → Status, puis testez :

Diffusion de beacon BLE (émettre une annonce BLE usurpée) :

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

Clavier HID BLE (émuler un clavier sans fil et taper) :

# Démarrer l'émulation HID
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":{}}}'

# Taper un 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!"}}}'

# Arrêter l'émulation HID
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":{}}}'

Émission IR (envoyer des codes de télécommande IR) :

# Code IR protocole NEC (bouton power TV générique)
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}}}'

Réception SubGHz (écouter les signaux sans fil sur 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}}}'

Remplacez 192.168.0.58 par l'adresse IP réelle de votre Flipper.

Ajoutez ensuite à votre configuration Claude Desktop (claude_desktop_config.json) :

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

5. Gérer la carte WiFi depuis le Flipper

Installez l'application compagnon Flipper MCP depuis flipper-app/ sur le Flipper Zero. Compilez avec ufbt et copiez le .fap dans SD:/apps/Tools/ :

cd flipper-app && ufbt   # produit flipper_mcp.fap
# Copiez flipper_mcp.fap sur votre carte SD Flipper dans apps/Tools/

L'application apparaît dans Apps → Tools → Flipper MCP et fournit :