flipper-mcp

Um servidor MCP (Model Context Protocol) em Rust que roda diretamente na WiFi Dev Board v1 (ESP32-S2) do Flipper Zero, permitindo que agentes de IA controlem um Flipper Zero pela rede.

O que é isto?

Este projeto coloca um servidor MCP no próprio Flipper. Qualquer cliente de IA compatível com MCP (Claude Desktop, Claude Code, etc.) pode se conectar e usar as capacidades do Flipper como ferramentas — SubGHz, NFC, RFID, IR, GPIO, BadUSB, iButton, armazenamento de arquivos e muito mais.

Diferente de outros projetos que exigem um computador host conectado por USB, o flipper-mcp roda no módulo WiFi ESP32-S2 acoplado ao Flipper. O Flipper se torna uma ferramenta autônoma e acessível pela rede.

Arquitetura

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

O ESP32-S2 executa um servidor HTTP que implementa o protocolo MCP. Ele traduz chamadas de ferramentas MCP em comandos CLI do Flipper Zero via UART a 115200 baud. Um servidor relay complementar possibilita acesso remoto a partir de qualquer rede.

Recursos

• ~30 ferramentas integradas cobrindo todos os aplicativos padrão do Flipper Zero
• Descoberta dinâmica de módulos — detecção automática de apps FAP do cartão SD + ferramentas orientadas por configuração TOML
• Configuração pelo próprio Flipper — configure o WiFi pelo FAP do Flipper (sem necessidade de celular, navegador ou scripts no PC)
• Transporte MCP duplo — Streamable HTTP (moderno) + SSE Legado (compatível com versões anteriores)
• Descoberta local — anúncio mDNS como flipper-mcp.local
• Acesso remoto — túnel WebSocket reverso através de um servidor relay (sem necessidade de encaminhamento de portas)
• Sem autenticação — projetado para cenários de pentest e pesquisa de segurança
• Servidor relay complementar — pequeno binário Rust para acesso entre redes, suporta múltiplos Flippers

Hardware Necessário

• Flipper Zero (qualquer versão de firmware com suporte a CLI)
• WiFi Dev Board v1 (módulo ESP32-S2-WROVER)

A qual dispositivo eu me conecto?

Etapa	Conecte-se a	Observações
Gravação do firmware	USB-C da WiFi Dev Board	A placa tem sua própria porta USB, separada do Flipper
Monitoramento serial	USB-C da WiFi Dev Board	Mesma conexão USB usada para gravação
Arquivos de configuração no cartão SD	Cartão SD do Flipper Zero	Insira o SD no Flipper, ou remova e monte no PC
Comandos de controle do servidor	Cartão SD do Flipper Zero	Crie o arquivo server.cmd em apps_data/flipper_mcp/
Comunicação UART	Automática	WiFi Dev Board e Flipper se conectam pelo conector GPIO
Requisições HTTP MCP	WiFi Dev Board IP:8080	Conecte-se pela sua rede WiFi

Pré-requisitos

• Rust — instale via rustup:

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

• Toolchain Xtensa — o ESP32-S2 requer uma toolchain Rust personalizada:

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

• Ferramenta de gravação e proxy de linker:

  cargo install espflash
  cargo install ldproxy
  

• Pacotes do 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
  

Início Rápido

Instruções completas de configuração em docs/SETUP.md

1. Compilar e gravar o 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 o WiFi

Crie config.txt no cartão SD do Flipper em SD:/apps_data/flipper_mcp/config.txt:

wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp

Ou configure diretamente pelo Flipper usando o FAP complementar (veja o Passo 5): Apps → Tools → Flipper MCP → Configure WiFi

No primeiro boot sem um arquivo de configuração, o ESP32 aguarda e grava status=needs_config no arquivo de status. O FAP do Flipper exibirá isso na tela Status.

4. Verificar se o servidor está funcionando

Antes de configurar um cliente de IA, confirme que o servidor está acessível com 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

Testar ferramentas MCP diretamente com curl

Obtenha o IP do Flipper no menu Flipper MCP → Status, depois teste:

Transmissão de beacon BLE (transmitir anúncio 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 um teclado sem fio e digitar):

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

Transmissão IR (enviar códigos de controle remoto 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}}}'

Recepção SubGHz (escutar sinais sem fio em 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}}}'

Substitua 192.168.0.58 pelo endereço IP real do seu Flipper.

Depois adicione à sua configuração do Claude Desktop (claude_desktop_config.json):

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

5. Gerenciar a placa WiFi pelo Flipper

Instale o app complementar Flipper MCP de flipper-app/ no Flipper Zero. Compile com ufbt e copie o .fap para SD:/apps/Tools/:

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

O app aparece em Apps → Tools → Flipper MCP e oferece:

Tela	O que faz
Status	Solicita uma atualização de status do ESP32, mostra IP, SSID, estado do servidor, versão
Start / Stop / Restart	Controla o ciclo de vida do servidor HTTP MCP
Reboot Board	Reinicia a WiFi Dev Board ESP32
Configure WiFi	Teclado na tela para inserir SSID + senha; grava config.txt no cartão SD
View Logs	Log de diagnóstico rolável gravado pelo ESP32 a cada 30 s
Tools List	Lista rolável de todas as ferramentas MCP atualmente registradas no ESP32
Refresh Modules	Dispara nova varredura de descoberta de FAPs + recarga de modules.toml no ESP32