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?

Prerequisiti

• Rust — installa tramite rustup:
  root@kitploit:~

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

• Toolchain Xtensa — l'ESP32-S2 richiede una toolchain Rust personalizzata:
  root@kitploit:~

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

• Strumento di flashing e linker proxy:
  root@kitploit:~

  cargo install espflash
  cargo install ldproxy
  

• Pacchetti di sistema (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
  

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:

L'app comunica tramite file sulla scheda SD (nessun cablaggio aggiuntivo oltre all'header GPIO). Configure WiFi è la procedura guidata del primo avvio — nessun telefono, browser o script PC necessario.

6. (Opzionale) Accesso remoto tramite relay

Self-hosted (esegui il binario ovunque):

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

Distribuzione cloud (AWS o GCP, con 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

Vedi RELAY.md per le istruzioni complete.

Strumenti disponibili

Strumenti personalizzati possono essere aggiunti tramite file di configurazione TOML o installando app FAP sulla scheda SD. Vedi OPERATIONS.md per comandi curl copia-incolla per ogni strumento.

Alternativa gratuita: Open WebUI + Ollama

Non hai bisogno di un abbonamento Claude per usare flipper-mcp. Open WebUI è un'interfaccia gratuita e self-hosted in stile ChatGPT che supporta nativamente MCP Streamable HTTP (v0.6.31+). Abbinala a Ollama per un controllo del Flipper guidato dall'AI completamente locale e offline.

1. Installa Ollama e scarica un modello con supporto agli strumenti

# 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. Avvia Open WebUI

# 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

Apri http://localhost:3000 nel tuo browser.

3. Connetti il server MCP del Flipper

1. Vai su Admin Settings (icona ingranaggio) → External Tools
2. Clicca su + Add Server
3. Imposta Type su MCP (Streamable HTTP)
4. Inserisci l'URL del server:
   • Locale: http://flipper-mcp.local:8080/mcp (o http://192.168.x.x:8080/mcp)
   • Tramite relay: https://relay.example.com/mcp
   • Da Docker: usa http://host.docker.internal:8080/mcp se il Flipper è sulla rete dell'host Docker
5. Imposta Authentication su None (flipper-mcp non ha autenticazione)
6. Save

Suggerimento: In Workspace → Models → (il tuo modello) → Advanced Parameters, imposta Function Calling su Default per i modelli più piccoli. Passa a Native solo per modelli con un forte supporto integrato agli strumenti (Llama 3.1 8B+, Qwen 2.5, Mistral).

4. Prompt di esempio

Una volta connesso, prova questi nella chat di Open WebUI:

Le attività agentiche multi-step funzionano meglio con modelli più grandi (Llama 3.1 70B, Qwen 2.5 72B, o modelli cloud tramite API compatibili con OpenAI). I modelli più piccoli gestiscono in modo affidabile le chiamate a singolo strumento.

Struttura del progetto

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

Documentazione

• SETUP.md — Configurazione completa da zero
• ARCHITECTURE.md — Approfondimento sul design del sistema
• API.md — Riferimento completo degli strumenti MCP
• OPERATIONS.md — Guida operativa con comandi curl per ogni strumento
• MODULE_DEVELOPMENT.md — Crea moduli personalizzati
• RELAY.md — Configurazione dell'accesso remoto
• HARDWARE.md — Cablaggio e dettagli hardware
• TROUBLESHOOTING.md — Problemi comuni e soluzioni
• DESIGN.md — Design tecnico e architettura del sistema

Per gli agenti AI

Vedi AGENTS.md per il contesto completo del progetto, le specifiche tecniche, l'architettura del sistema e tutto ciò che serve per continuare lo sviluppo di questo progetto.

Licenza

MIT