A Rust MCP server that runs directly on the Flipper Zero's WiFi Dev Board, letting authorized AI clients drive SubGHz, NFC, IR, BLE, and GPIO tools over the network.
| Tool | roostercoopllc/flipper-mcp — Rust MCP server running on the Flipper Zero's ESP32-S2 WiFi Dev Board |
| Category | Embedded AI-tool bridge / hardware control plane (Rust, MCP, ESP32) |
| Primary Use | Letting an MCP-compatible AI client operate a Flipper Zero's SubGHz, NFC, RFID, IR, GPIO, BLE, and storage functions during authorized lab work |
| Safe Use | For authorized security assessments, personal lab hardware, and defensive research on radio and HID attack surfaces you own or are permitted to test |
| Telemetry Note | Advertises itself via mDNS as flipper-mcp.local on port 8080 with no authentication; defenders on the LAN can spot the advertisement, HTTP health endpoint, and any reverse WebSocket relay traffic |
Most attempts to script a Flipper Zero from an AI client assume a USB tether: a host computer runs the bridge, and the multi-tool hangs off a laptop. roostercoopllc/flipper-mcp inverts that arrangement entirely. It is a Rust implementation of the Model Context Protocol that compiles for and flashes onto the ESP32-S2-WROVER module of the WiFi Dev Board v1, the little companion board that physically snaps onto the Flipper's GPIO header. Once running, the Flipper becomes a standalone, network-addressable device, and any MCP client — Claude Desktop, Claude Code, or a self-hosted Open WebUI instance — can invoke its hardware capabilities as ordinary tool calls.
The architecture, as the README diagrams it, is a clean two-hop translation chain. On the local network, an MCP client speaks plain HTTP to flipper-mcp.local:8080, where the ESP32-S2 runs the MCP server; the server in turn talks to the Flipper Zero itself over UART at 115200 baud, translating tool calls into Flipper CLI commands. For cross-network operation, the design adds a relay layer: the client hits a relay server over HTTP, and the ESP32 opens a reverse WebSocket tunnel out to it, which neatly sidesteps port forwarding and NAT traversal. That relay is a small companion Rust binary that can be self-hosted or spun up in the cloud via provided OpenTofu/Terraform infrastructure scripts for AWS or GCP.
The tool surface is broad — roughly thirty built-in tools covering the stock Flipper application set. SubGHz operations include subghz_tx, subghz_rx, subghz_decode_raw, subghz_chat, and subghz_tx_from_file; NFC is served by nfc_detect, nfc_read, nfc_emulate, and nfc_field; low-frequency RFID by rfid_read, rfid_emulate, and rfid_write. Infrared gets ir_tx and ir_rx, GPIO gets gpio_read, gpio_write, and gpio_set_mode, and iButton 1-Wire fobs get ibutton_read and ibutton_emulate. Storage primitives (storage_list, storage_read, storage_write, storage_remove, storage_stat) and a suite of system_* tools for device info, power, process listing, and uptime round out the inventory.
Two categories deserve particular caution and particular interest from defenders. BadUSB is exposed via badusb_run and badusb_list, and BLE includes a full HID emulation set — ble_hid_start, ble_hid_type, ble_hid_press, ble_hid_mouse, ble_hid_stop — plus ble_beacon for transmitting crafted advertisement data. In an authorized engagement or lab, this is precisely the attack surface you want an operator-in-the-loop AI to demonstrate under supervision; on someone else's hardware, it is straightforwardly an attack tool. The educational value here is architectural: understanding how a language model can chain ble_hid_start and ble_hid_type into a keystroke-injection sequence is exactly the awareness defenders need when briefing clients on unattended workstation risk.
What makes the project more than a static RPC wrapper is its extensibility model. The server performs dynamic module discovery: FAP apps installed on the Flipper's SD card are auto-detected and registered as callable tools (surfacing as app_launch_{name}), and additional custom tools can be declared through TOML configuration. A companion Flipper app, built with ufbt and dropped into SD:/apps/Tools/, provides an on-device management console — status, start/stop/restart of the HTTP server, board reboot, an on-device WiFi configuration wizard with an on-screen keyboard, a scrollable log view written every thirty seconds, a live tools list, and a module-rescan trigger. Notably, the FAP and the ESP32 communicate through SD card files rather than extra wiring, which is an elegant reuse of the only shared medium the two chips already have.
Operational configuration follows a Flipper-first philosophy. WiFi credentials live in SD:/apps_data/flipper_mcp/config.txt with wifi_ssid, wifi_password, and device_name keys, and on first boot without a config the ESP32 idles and writes status=needs_config, which the FAP surfaces on its status screen. Server lifecycle commands are likewise file-driven via a server.cmd file in the same directory. Verification is refreshingly manual: a curl http://flipper-mcp.local:8080/health health check and a scripts/test-connection.sh script that initializes the MCP session and lists registered tools, with an optional IP argument for networks where mDNS resolution is flaky.
The build pipeline is standard ESP Rust, though not trivial. Beyond a rustup-installed toolchain, the ESP32-S2 target needs the Xtensa toolchain via espup install and a sourced export-esp.sh in every shell, plus espflash and ldproxy from cargo install. The firmware then builds with cargo build --release --target xtensa-esp32s2-espidf inside the firmware/ directory and flashes through the dev board's own USB-C port — the README is careful to note that flashing and serial monitoring use the board's port, distinct from the Flipper's, since that distinction trips people up. Debian/Ubuntu/Kali users get a one-line apt dependency list covering libudev-dev, libssl-dev, cmake, and ninja-build.
On the AI-client side, the project is refreshingly vendor-neutral. Alongside the obvious claude_desktop_config.json integration — a three-line mcpServers entry pointing at http://flipper-mcp.local:8080/mcp — the README documents a fully free, fully offline path using Open WebUI (v0.6.31+) paired with Ollama, suggesting tool-capable local models like llama3.1, qwen2.5, or mistral. This matters for operational hygiene: an assessor who wants an LLM orchestrating hardware tests without traffic leaving the engagement network can run the entire stack — model, MCP client, and Flipper server — air-gapped from the internet, with the relay path as the only thing deliberately exposed.
From a defensive documentation standpoint, the security posture of the server itself is the loudest signal in the README: it ships with no authentication, explicitly framed as designed for pentesting and security research scenarios. On a lab or engagement network that is a documented, accepted risk; anywhere else it is a remotely controllable radio and HID device with an open 8080 port. Defenders should know the observables: an mDNS advertisement for flipper-mcp.local, unauthenticated JSON-RPC POST traffic to an /mcp endpoint on port 8080, and outbound WebSocket connections to a ws:// relay on 9090 if the tunnel mode is in use. None of this is stealthy by design — it is a research instrument, not an implant, and it announces itself on the wire.
Where flipper-mcp fits in an authorized workflow is best understood as force multiplication for hardware test coverage. An operator running physical-security reviews of badge systems can have an AI agent sweep nfc_detect/rfid_read results into a report, cross-reference captured IR codes against protocol tables via ir_rx, and inventory SD storage with storage_stat — all while the human retains judgment over any transmission step. The repo's docs/OPERATIONS.md catalogs copy-paste invocations for every tool, and docs/RELAY.md covers cloud relay deployment, so the documentation supports both bench work and distributed engagements.
At 22 stars, MIT-licensed, and written in Rust, this is a young project rather than a hardened product — expect rough edges around the Xtensa toolchain and edge cases in FAP discovery. But as a demonstration of where agent-driven hardware interaction is heading, it is one of the more coherent designs in the Flipper ecosystem: the MCP server lives on the device, the relay handles reachability, the FAP handles local administration, and the model is pluggable. For professionals documenting the convergence of LLM tool-calling with physical-layer attack tooling, it is a reference implementation worth studying — inside a lab, with your own hardware, on a network you control.
roostercoopllc/flipper-mcp.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.