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?

Pré-requisitos

• Rust — instale via rustup:
  root@kitploit:~

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

• Toolchain Xtensa — o ESP32-S2 requer uma toolchain Rust personalizada:
  root@kitploit:~

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

• Ferramenta de gravação e proxy de linker:
  root@kitploit:~

  cargo install espflash
  cargo install ldproxy
  

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

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:

O app se comunica via arquivos no cartão SD (sem fiação extra além do conector GPIO). Configure WiFi é o assistente de primeiro boot — sem necessidade de celular, navegador ou scripts no PC.

6. (Opcional) Acesso remoto via relay

Auto-hospedado (execute o binário em qualquer lugar):

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

Implantação em nuvem (AWS ou GCP, com 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

Veja RELAY.md para instruções completas.

Ferramentas Disponíveis

Ferramentas personalizadas podem ser adicionadas via arquivos de configuração TOML ou instalando apps FAP no cartão SD. Veja OPERATIONS.md para comandos curl prontos para copiar e colar de cada ferramenta.

Alternativa Gratuita: Open WebUI + Ollama

Você não precisa de uma assinatura do Claude para usar o flipper-mcp. O Open WebUI é uma interface gratuita e auto-hospedada no estilo ChatGPT que suporta nativamente MCP Streamable HTTP (v0.6.31+). Combine-o com o Ollama para controle do Flipper por IA totalmente local e offline.

1. Instale o Ollama e baixe um modelo com suporte a ferramentas

# 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. Inicie o 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

Abra http://localhost:3000 no seu navegador.

3. Conecte o servidor MCP do Flipper

1. Vá em Admin Settings (ícone de engrenagem) → External Tools
2. Clique em + Add Server
3. Defina Type como MCP (Streamable HTTP)
4. Insira a URL do servidor:
   • Local: http://flipper-mcp.local:8080/mcp (ou http://192.168.x.x:8080/mcp)
   • Via relay: https://relay.example.com/mcp
   • A partir do Docker: use http://host.docker.internal:8080/mcp se o Flipper estiver na rede do host Docker
5. Defina Authentication como None (o flipper-mcp não tem autenticação)
6. Save

Dica: Em Workspace → Models → (seu modelo) → Advanced Parameters, defina Function Calling como Default para modelos menores. Só mude para Native em modelos com forte suporte integrado a ferramentas (Llama 3.1 8B+, Qwen 2.5, Mistral).

4. Exemplos de prompts

Depois de conectado, experimente estes no chat do Open WebUI:

Tarefas agênticas de múltiplas etapas funcionam melhor com modelos maiores (Llama 3.1 70B, Qwen 2.5 72B, ou modelos em nuvem via APIs compatíveis com OpenAI). Modelos menores lidam de forma confiável com chamadas de uma única ferramenta.

Estrutura do Projeto

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

Documentação

• SETUP.md — Configuração completa do zero
• ARCHITECTURE.md — Análise aprofundada do design do sistema
• API.md — Referência completa das ferramentas MCP
• OPERATIONS.md — Guia de operações com comandos curl para cada ferramenta
• MODULE_DEVELOPMENT.md — Crie módulos personalizados
• RELAY.md — Configuração de acesso remoto
• HARDWARE.md — Detalhes de fiação e hardware
• TROUBLESHOOTING.md — Problemas comuns e correções
• DESIGN.md — Design técnico e arquitetura do sistema

Para Agentes de IA

Veja AGENTS.md para contexto completo do projeto, especificações técnicas, arquitetura do sistema e tudo o que é necessário para continuar o desenvolvimento deste projeto.

Licença

MIT