flipper-mcp

A Rust MCP (Model Context Protocol) server that runs directly on the Flipper Zero's WiFi Dev Board v1 (ESP32-S2), enabling AI agents to control a Flipper Zero over the network.

What is this?

This project puts an MCP server on the Flipper itself. Any MCP-compatible AI client (Claude Desktop, Claude Code, etc.) can connect and use the Flipper's capabilities as tools — SubGHz, NFC, RFID, IR, GPIO, BadUSB, iButton, file storage, and more.

Unlike other projects that require a USB-connected host computer, flipper-mcp runs on the ESP32-S2 WiFi module attached to the Flipper. The Flipper becomes a standalone, network-accessible tool.

Architecture

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

The ESP32-S2 runs an HTTP server implementing the MCP protocol. It translates MCP tool calls into Flipper Zero CLI commands over UART at 115200 baud. A companion relay server enables remote access from any network.

Features

• ~30 built-in tools covering all default Flipper Zero applications
• Dynamic module discovery — auto-detect FAP apps from SD card + TOML config-driven tools
• Flipper-first setup — configure WiFi from the Flipper FAP (no phone, browser, or PC scripts needed)
• Dual MCP transport — Streamable HTTP (modern) + Legacy SSE (backward compatible)
• Local discovery — mDNS advertisement as flipper-mcp.local
• Remote access — reverse WebSocket tunnel through a relay server (no port forwarding needed)
• No authentication — designed for pentesting and security research scenarios
• Companion relay server — small Rust binary for cross-network access, supports multiple Flippers

Hardware Required

• Flipper Zero (any firmware version with CLI support)
• WiFi Dev Board v1 (ESP32-S2-WROVER module)

Which device do I connect to?

Prerequisites

• Rust — install via rustup:

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

• Xtensa toolchain — ESP32-S2 requires a custom Rust toolchain:

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

• Flash tool & linker proxy:

  cargo install espflash
  cargo install ldproxy
  

• System packages (Debian/Ubuntu/Kali):

  sudo apt install -y git curl gcc build-essential pkg-config libudev-dev libssl-dev python3 python3-venv cmake ninja-build
  

Quick Start

Full setup instructions in docs/SETUP.md

1. Build & flash 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. Configure WiFi

Create config.txt on the Flipper SD card at SD:/apps_data/flipper_mcp/config.txt:

wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp

Or configure directly from the Flipper using the companion FAP (see Step 5): Apps → Tools → Flipper MCP → Configure WiFi

On first boot without a config file, the ESP32 waits and writes status=needs_config to the status file. The Flipper FAP will display this on the Status screen.

4. Verify the server is working

Before configuring an AI client, confirm the server is reachable with 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

Test MCP tools directly with curl

Get the Flipper's IP from the Flipper MCP → Status menu, then test:

BLE beacon broadcast (transmit spoofed BLE advertisement):

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

BLE HID keyboard (emulate a wireless keyboard and type):

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

IR transmit (send IR remote control codes):

# 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}}}'

SubGHz receive (listen for wireless signals on 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}}}'

Replace 192.168.0.58 with your Flipper's actual IP address.

Then add to your Claude Desktop config (claude_desktop_config.json):

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

5. Manage the WiFi board from the Flipper

Install the companion Flipper MCP app from flipper-app/ onto the Flipper Zero. Build with ufbt and copy the .fap to SD:/apps/Tools/:

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

The app appears in Apps → Tools → Flipper MCP and provides:

The app communicates via SD card files (no extra wiring beyond the GPIO header). Configure WiFi is the first-boot wizard — no phone, browser, or PC scripts required.

6. (Optional) Remote access via relay

Self-hosted (run the binary anywhere):

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

Cloud deployment (AWS or GCP, with 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

See RELAY.md for full instructions.

Available Tools

Custom tools can be added via TOML config files or by installing FAP apps on the SD card. See OPERATIONS.md for copy-paste curl commands for every tool.

Free Alternative: Open WebUI + Ollama

You don't need a Claude subscription to use flipper-mcp. Open WebUI is a free, self-hosted ChatGPT-style interface that natively supports MCP Streamable HTTP (v0.6.31+). Pair it with Ollama for fully local, offline AI-driven Flipper control.

1. Install Ollama and pull a tool-capable model

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

Open http://localhost:3000 in your browser.

3. Connect the Flipper MCP server

1. Go to Admin Settings (gear icon) → External Tools
2. Click + Add Server
3. Set Type to MCP (Streamable HTTP)
4. Enter the server URL:
   • Local: http://flipper-mcp.local:8080/mcp (or http://192.168.x.x:8080/mcp)
   • Via relay: https://relay.example.com/mcp
   • From Docker: use http://host.docker.internal:8080/mcp if the Flipper is on the Docker host's network
5. Set Authentication to None (flipper-mcp has no auth)
6. Save

Tip: Under Workspace → Models → (your model) → Advanced Parameters, set Function Calling to Default for smaller models. Only switch to Native for models with strong built-in tool support (Llama 3.1 8B+, Qwen 2.5, Mistral).

4. Example prompts

Once connected, try these in the Open WebUI chat:

Multi-step agentic tasks work best with larger models (Llama 3.1 70B, Qwen 2.5 72B, or cloud models via OpenAI-compatible APIs). Smaller models handle single-tool calls reliably.

Project Structure

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

Documentation

• SETUP.md — Full setup from scratch
• ARCHITECTURE.md — System design deep dive
• API.md — Complete MCP tool reference
• OPERATIONS.md — Operations guide with curl commands for every tool
• MODULE_DEVELOPMENT.md — Create custom modules
• RELAY.md — Remote access setup
• HARDWARE.md — Wiring and hardware details
• TROUBLESHOOTING.md — Common issues and fixes
• DESIGN.md — Technical design and system architecture

For AI Agents

See AGENTS.md for complete project context, technical specifications, system architecture, and everything needed to continue development on this project.

License

MIT