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?

Stage	Connect to	Notes
Flashing firmware	WiFi Dev Board USB-C	Board has its own USB port, separate from Flipper
Serial monitoring	WiFi Dev Board USB-C	Same USB connection as flashing
SD card config files	Flipper Zero SD card	Insert SD into Flipper, or remove and mount on PC
Server control commands	Flipper Zero SD card	Create server.cmd file in apps_data/flipper_mcp/
UART communication	Automatic	WiFi Dev Board and Flipper connect via GPIO header
MCP HTTP requests	WiFi Dev Board IP:8080	Connect over your WiFi network

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:

Screen	What it does
Status	Requests a fresh status update from the ESP32, shows IP, SSID, server state, version
Start / Stop / Restart	Controls the MCP HTTP server lifecycle
Reboot Board	Restarts the ESP32 WiFi Dev Board
Configure WiFi	On-screen keyboard to enter SSID + password; writes config.txt to SD card
View Logs	Scrollable diagnostic log written by the ESP32 every 30 s
Tools List	Scrollable list of all MCP tools currently registered on the ESP32
Refresh Modules	Triggers FAP discovery rescan + modules.toml reload on the ESP32

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