flipper-mcp

Un server MCP (Model Context Protocol) in Rust che viene eseguito direttamente sulla WiFi Dev Board v1 (ESP32-S2) del Flipper Zero, consentendo agli agenti AI di controllare un Flipper Zero attraverso la rete.

Cos'è questo?

Questo progetto mette un server MCP sul Flipper stesso. Qualsiasi client AI compatibile con MCP (Claude Desktop, Claude Code, ecc.) può connettersi e utilizzare le capacità del Flipper come strumenti — SubGHz, NFC, RFID, IR, GPIO, BadUSB, iButton, archiviazione file e altro ancora.

A differenza di altri progetti che richiedono un computer host collegato via USB, flipper-mcp viene eseguito sul modulo WiFi ESP32-S2 collegato al Flipper. Il Flipper diventa uno strumento autonomo e accessibile via rete.

Architettura

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

L'ESP32-S2 esegue un server HTTP che implementa il protocollo MCP. Traduce le chiamate agli strumenti MCP in comandi CLI del Flipper Zero via UART a 115200 baud. Un server relay complementare consente l'accesso remoto da qualsiasi rete.

Funzionalità

• ~30 strumenti integrati che coprono tutte le applicazioni predefinite del Flipper Zero
• Scoperta dinamica dei moduli — rilevamento automatico delle app FAP dalla scheda SD + strumenti guidati da configurazione TOML
• Configurazione Flipper-first — configura il WiFi dal FAP del Flipper (nessun telefono, browser o script PC necessario)
• Doppio trasporto MCP — Streamable HTTP (moderno) + Legacy SSE (retrocompatibile)
• Scoperta locale — annuncio mDNS come flipper-mcp.local
• Accesso remoto — tunnel WebSocket inverso attraverso un server relay (nessun port forwarding necessario)
• Nessuna autenticazione — progettato per scenari di pentesting e ricerca sulla sicurezza
• Server relay complementare — piccolo binario Rust per l'accesso cross-network, supporta più Flipper

Hardware richiesto

• Flipper Zero (qualsiasi versione di firmware con supporto CLI)
• WiFi Dev Board v1 (modulo ESP32-S2-WROVER)

A quale dispositivo mi collego?

Fase	Connettersi a	Note
Flashing del firmware	USB-C della WiFi Dev Board	La scheda ha la propria porta USB, separata dal Flipper
Monitoraggio seriale	USB-C della WiFi Dev Board	Stessa connessione USB del flashing
File di configurazione sulla scheda SD	Scheda SD del Flipper Zero	Inserisci la SD nel Flipper, oppure rimuovila e montala sul PC
Comandi di controllo del server	Scheda SD del Flipper Zero	Crea il file server.cmd in apps_data/flipper_mcp/
Comunicazione UART	Automatica	WiFi Dev Board e Flipper si collegano tramite header GPIO
Richieste HTTP MCP	IP della WiFi Dev Board:8080	Connettiti tramite la tua rete WiFi

Prerequisiti

• Rust — installa tramite rustup:

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

• Toolchain Xtensa — l'ESP32-S2 richiede una toolchain Rust personalizzata:

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

• Strumento di flashing e linker proxy:

  cargo install espflash
  cargo install ldproxy
  

• Pacchetti di sistema (Debian/Ubuntu/Kali):

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

Avvio rapido

Istruzioni complete di configurazione in docs/SETUP.md

1. Compila e flasha il 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. Configura il WiFi

Crea config.txt sulla scheda SD del Flipper in SD:/apps_data/flipper_mcp/config.txt:

wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp

Oppure configura direttamente dal Flipper usando il FAP complementare (vedi Passo 5): Apps → Tools → Flipper MCP → Configure WiFi

Al primo avvio senza un file di configurazione, l'ESP32 attende e scrive status=needs_config nel file di stato. Il FAP del Flipper lo visualizzerà nella schermata Status.

4. Verifica che il server funzioni

Prima di configurare un client AI, conferma che il server sia raggiungibile con 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

Testa gli strumenti MCP direttamente con curl

Ottieni l'IP del Flipper dal menu Flipper MCP → Status, poi testa:

Trasmissione beacon BLE (trasmette un annuncio BLE falsificato):

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

Tastiera HID BLE (emula una tastiera wireless e digita):

# 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":{}}}'

Trasmissione IR (invia codici di telecomando 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}}}'

Ricezione SubGHz (ascolta segnali wireless su 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}}}'

Sostituisci 192.168.0.58 con l'indirizzo IP effettivo del tuo Flipper.

Poi aggiungi alla tua configurazione di Claude Desktop (claude_desktop_config.json):

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

5. Gestisci la scheda WiFi dal Flipper

Installa l'app complementare Flipper MCP da flipper-app/ sul Flipper Zero. Compila con ufbt e copia il .fap in SD:/apps/Tools/:

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

L'app appare in Apps → Tools → Flipper MCP e fornisce: