roostercoopllc/flipper-mcpServidor MCP impulsado por IA para Flipper Zero. Controla SubGHz, NFC, RFID, IR, BLE, GPIO y más por WiFi usando Claude o cualquier cliente MCP.
Un servidor MCP (Model Context Protocol) en Rust que se ejecuta directamente en la WiFi Dev Board v1 (ESP32-S2) del Flipper Zero, lo que permite a los agentes de IA controlar un Flipper Zero a través de la red.
Este proyecto coloca un servidor MCP en el propio Flipper. Cualquier cliente de IA compatible con MCP (Claude Desktop, Claude Code, etc.) puede conectarse y usar las capacidades del Flipper como herramientas — SubGHz, NFC, RFID, IR, GPIO, BadUSB, iButton, almacenamiento de archivos y más.
A diferencia de otros proyectos que requieren un ordenador host conectado por USB, flipper-mcp se ejecuta en el módulo WiFi ESP32-S2 conectado al Flipper. El Flipper se convierte en una herramienta autónoma y accesible por red.
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
El ESP32-S2 ejecuta un servidor HTTP que implementa el protocolo MCP. Traduce las llamadas a herramientas MCP en comandos CLI del Flipper Zero a través de UART a 115200 baudios. Un servidor relay complementario permite el acceso remoto desde cualquier red.
flipper-mcp.local¿A qué dispositivo me conecto?
| Etapa | Conectar a | Notas |
|---|---|---|
| Flashear firmware | USB-C de la WiFi Dev Board | La placa tiene su propio puerto USB, independiente del Flipper |
| Monitorización serie | USB-C de la WiFi Dev Board | La misma conexión USB que para flashear |
| Archivos de configuración en la SD | Tarjeta SD del Flipper Zero | Inserta la SD en el Flipper, o extráela y móntala en el PC |
| Comandos de control del servidor | Tarjeta SD del Flipper Zero | Crea el archivo server.cmd en apps_data/flipper_mcp/ |
| Comunicación UART | Automática | La WiFi Dev Board y el Flipper se conectan mediante el conector GPIO |
| Peticiones HTTP MCP | IP de la WiFi Dev Board:8080 | Conéctate a través de tu red WiFi |
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install espup
espup install
source ~/export-esp.sh # Run this in every new terminal
cargo install espflash
cargo install ldproxy
sudo apt install -y git curl gcc build-essential pkg-config libudev-dev libssl-dev python3 python3-venv cmake ninja-build
Instrucciones completas de configuración en docs/SETUP.md
source ~/export-esp.sh
cd firmware
cargo build --release --target xtensa-esp32s2-espidf
espflash flash --monitor target/xtensa-esp32s2-espidf/release/flipper-mcp
Crea config.txt en la tarjeta SD del Flipper en SD:/apps_data/flipper_mcp/config.txt:
wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp
O configura directamente desde el Flipper usando el FAP complementario (ver Paso 5):
Apps → Tools → Flipper MCP → Configure WiFi
En el primer arranque sin archivo de configuración, el ESP32 espera y escribe status=needs_config en el archivo de estado. El FAP del Flipper mostrará esto en la pantalla Status.
Antes de configurar un cliente de IA, confirma que el servidor es accesible 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
Obtén la IP del Flipper desde el menú Flipper MCP → Status, y luego prueba:
Emisión de beacon BLE (transmitir un anuncio BLE falsificado):
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"}}}'
Teclado HID BLE (emular un teclado inalámbrico y escribir):
# 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":{}}}'
Transmisión IR (enviar códigos de mando a distancia 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}}}'
Recepción SubGHz (escuchar señales inalámbricas en 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}}}'
Sustituye 192.168.0.58 por la dirección IP real de tu Flipper.
Luego añade esto a tu configuración de Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"flipper": {
"url": "http://flipper-mcp.local:8080/mcp"
}
}
}
Instala la aplicación complementaria Flipper MCP desde flipper-app/ en el Flipper Zero. Compílala con ufbt y copia el .fap a SD:/apps/Tools/:
cd flipper-app && ufbt # produces flipper_mcp.fap
# Copy flipper_mcp.fap to your Flipper SD card under apps/Tools/
La aplicación aparece en Apps → Tools → Flipper MCP y proporciona: