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 ?

Prérequis

• Rust — installez via rustup :
  root@kitploit:~

  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 :
  root@kitploit:~

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

• Outil de flash & proxy de linker :
  root@kitploit:~

  cargo install espflash
  cargo install ldproxy
  

• Paquets système (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
  

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 :

L'application communique via des fichiers sur carte SD (aucun câblage supplémentaire au-delà du connecteur GPIO). Configure WiFi est l'assistant de premier démarrage — aucun téléphone, navigateur ou script PC nécessaire.

6. (Optionnel) Accès distant via relais

Auto-hébergé (exécutez le binaire n'importe où) :

./scripts/build-relay.sh
./target/release/flipper-mcp-relay --listen 0.0.0.0:9090
# Ajoutez ensuite relay_url à config.txt sur la carte SD du Flipper :
# relay_url=ws://your-server:9090/tunnel

Déploiement cloud (AWS ou GCP, avec TLS + DNS) :

# Initialisez le stockage d'état, puis déployez
./infra/bootstrap/aws.sh   # ou ./infra/bootstrap/gcp.sh
cd infra/aws && cp terraform.tfvars.example terraform.tfvars
tofu init && tofu apply
# Affiche l'URL du relais et une commande wifi-config.sh prête à coller

Voir RELAY.md pour les instructions complètes.

Outils disponibles

Des outils personnalisés peuvent être ajoutés via des fichiers de configuration TOML ou en installant des applications FAP sur la carte SD. Voir OPERATIONS.md pour des commandes curl prêtes à copier-coller pour chaque outil.

Alternative gratuite : Open WebUI + Ollama

Vous n'avez pas besoin d'un abonnement Claude pour utiliser flipper-mcp. Open WebUI est une interface gratuite et auto-hébergée de type ChatGPT qui prend nativement en charge MCP Streamable HTTP (v0.6.31+). Associez-la à Ollama pour un contrôle du Flipper piloté par IA entièrement local et hors ligne.

1. Installer Ollama et récupérer un modèle compatible outils

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

# Récupérer un modèle avec support d'appel d'outils
ollama pull llama3.1        # 8B — bon équilibre entre vitesse et capacités
# ou : ollama pull qwen2.5   # fort appel d'outils, bon en sortie structurée
# ou : ollama pull mistral    # léger, utilisation d'outils rapide

2. Démarrer Open WebUI

# Docker (recommandé) — se connecte automatiquement à Ollama sur localhost
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

# Ou sans Docker :
pip install open-webui
open-webui serve

Ouvrez http://localhost:3000 dans votre navigateur.

3. Connecter le serveur MCP du Flipper

1. Allez dans Admin Settings (icône engrenage) → External Tools
2. Cliquez sur + Add Server
3. Réglez Type sur MCP (Streamable HTTP)
4. Saisissez l'URL du serveur :
   • Local : http://flipper-mcp.local:8080/mcp (ou http://192.168.x.x:8080/mcp)
   • Via relais : https://relay.example.com/mcp
   • Depuis Docker : utilisez http://host.docker.internal:8080/mcp si le Flipper est sur le réseau de l'hôte Docker
5. Réglez Authentication sur None (flipper-mcp n'a pas d'authentification)
6. Save

Astuce : Sous Workspace → Models → (votre modèle) → Advanced Parameters, réglez Function Calling sur Default pour les petits modèles. Ne passez à Native que pour les modèles avec un fort support d'outils intégré (Llama 3.1 8B+, Qwen 2.5, Mistral).

4. Exemples de prompts

Une fois connecté, essayez ceci dans le chat Open WebUI :

Les tâches agentiques multi-étapes fonctionnent mieux avec des modèles plus grands (Llama 3.1 70B, Qwen 2.5 72B, ou des modèles cloud via des API compatibles OpenAI). Les petits modèles gèrent de manière fiable les appels à un seul outil.

Structure du projet

flipper-mcp/
├── firmware/          # Firmware ESP32-S2 (Rust, esp-idf-svc)
├── relay/             # Serveur relais compagnon (Rust, tokio/axum)
├── flipper-app/       # FAP Flipper Zero — interface de gestion embarquée (C, ufbt)
├── infra/             # IaC OpenTofu — déploiement du relais cloud (AWS + GCP)
├── config/            # Exemples de configurations de modules
├── scripts/           # Scripts d'aide pour la compilation, le flash et l'installation
└── docs/              # Architecture, installation, API, dépannage

Documentation

• SETUP.md — Installation complète depuis zéro
• ARCHITECTURE.md — Exploration approfondie de la conception du système
• API.md — Référence complète des outils MCP
• OPERATIONS.md — Guide d'exploitation avec commandes curl pour chaque outil
• MODULE_DEVELOPMENT.md — Créer des modules personnalisés
• RELAY.md — Configuration de l'accès distant
• HARDWARE.md — Détails du câblage et du matériel
• TROUBLESHOOTING.md — Problèmes courants et correctifs
• DESIGN.md — Conception technique et architecture du système

Pour les agents IA

Voir AGENTS.md pour le contexte complet du projet, les spécifications techniques, l'architecture du système, et tout ce qui est nécessaire pour poursuivre le développement de ce projet.

Licence

MIT