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

¿Qué es esto?

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.

Arquitectura

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.

Características

• ~30 herramientas integradas que cubren todas las aplicaciones predeterminadas del Flipper Zero
• Descubrimiento dinámico de módulos — autodetección de aplicaciones FAP desde la tarjeta SD + herramientas basadas en configuración TOML
• Configuración centrada en el Flipper — configura el WiFi desde el FAP del Flipper (sin necesidad de teléfono, navegador ni scripts de PC)
• Doble transporte MCP — Streamable HTTP (moderno) + Legacy SSE (compatible con versiones anteriores)
• Descubrimiento local — anuncio mDNS como flipper-mcp.local
• Acceso remoto — túnel WebSocket inverso a través de un servidor relay (sin necesidad de reenvío de puertos)
• Sin autenticación — diseñado para escenarios de pentesting e investigación de seguridad
• Servidor relay complementario — pequeño binario en Rust para acceso entre redes, compatible con múltiples Flippers

Hardware necesario

• Flipper Zero (cualquier versión de firmware con soporte CLI)
• WiFi Dev Board v1 (módulo ESP32-S2-WROVER)

¿A qué dispositivo me conecto?

Requisitos previos

• Rust — instálalo mediante rustup:
  root@kitploit:~

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

• Toolchain de Xtensa — el ESP32-S2 requiere una toolchain de Rust personalizada:
  root@kitploit:~

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

• Herramienta de flasheo y proxy del enlazador:
  root@kitploit:~

  cargo install espflash
  cargo install ldproxy
  

• Paquetes del 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
  

Inicio rápido

Instrucciones completas de configuración en docs/SETUP.md

1. Compilar y flashear el 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. Configurar el WiFi

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.

4. Verificar que el servidor funciona

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

Probar las herramientas MCP directamente con curl

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

5. Gestionar la placa WiFi desde el Flipper

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:

La aplicación se comunica mediante archivos en la tarjeta SD (sin cableado adicional más allá del conector GPIO). Configure WiFi es el asistente de primer arranque — no requiere teléfono, navegador ni scripts de PC.

6. (Opcional) Acceso remoto mediante relay

Autoalojado (ejecuta el binario donde quieras):

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

Despliegue en la nube (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

Consulta RELAY.md para las instrucciones completas.

Herramientas disponibles

Se pueden añadir herramientas personalizadas mediante archivos de configuración TOML o instalando aplicaciones FAP en la tarjeta SD. Consulta OPERATIONS.md para comandos curl listos para copiar y pegar de cada herramienta.

Alternativa gratuita: Open WebUI + Ollama

No necesitas una suscripción a Claude para usar flipper-mcp. Open WebUI es una interfaz gratuita y autoalojada al estilo ChatGPT que soporta de forma nativa MCP Streamable HTTP (v0.6.31+). Combínala con Ollama para un control del Flipper totalmente local y offline impulsado por IA.

1. Instalar Ollama y descargar un modelo con capacidad de herramientas

# 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. Iniciar 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

Abre http://localhost:3000 en tu navegador.

3. Conectar el servidor MCP del Flipper

1. Ve a Admin Settings (icono de engranaje) → External Tools
2. Haz clic en + Add Server
3. Establece Type en MCP (Streamable HTTP)
4. Introduce la URL del servidor:
   • Local: http://flipper-mcp.local:8080/mcp (o http://192.168.x.x:8080/mcp)
   • Vía relay: https://relay.example.com/mcp
   • Desde Docker: usa http://host.docker.internal:8080/mcp si el Flipper está en la red del host de Docker
5. Establece Authentication en None (flipper-mcp no tiene autenticación)
6. Save

Consejo: En Workspace → Models → (tu modelo) → Advanced Parameters, establece Function Calling en Default para modelos más pequeños. Cambia a Native solo para modelos con un fuerte soporte de herramientas integrado (Llama 3.1 8B+, Qwen 2.5, Mistral).

4. Prompts de ejemplo

Una vez conectado, prueba estos en el chat de Open WebUI:

Las tareas agénticas de varios pasos funcionan mejor con modelos más grandes (Llama 3.1 70B, Qwen 2.5 72B, o modelos en la nube mediante APIs compatibles con OpenAI). Los modelos más pequeños manejan llamadas de una sola herramienta de forma fiable.

Estructura del proyecto

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

Documentación

• SETUP.md — Configuración completa desde cero
• ARCHITECTURE.md — Análisis en profundidad del diseño del sistema
• API.md — Referencia completa de las herramientas MCP
• OPERATIONS.md — Guía de operaciones con comandos curl para cada herramienta
• MODULE_DEVELOPMENT.md — Crear módulos personalizados
• RELAY.md — Configuración del acceso remoto
• HARDWARE.md — Detalles de cableado y hardware
• TROUBLESHOOTING.md — Problemas comunes y soluciones
• DESIGN.md — Diseño técnico y arquitectura del sistema

Para agentes de IA

Consulta AGENTS.md para obtener el contexto completo del proyecto, especificaciones técnicas, arquitectura del sistema y todo lo necesario para continuar el desarrollo de este proyecto.

Licencia

MIT