flipper-mcp 🐬

Control your Flipper Zero from Claude (or any MCP client) over USB — no COM port needed. Screenshots, RF / NFC / IR / GPIO, and build & deploy your own apps (FAPs) — all over USB. Works on macOS, Linux, and Windows.

Why it's different

Most Flipper MCP servers just wrap the serial CLI. flipper-mcp goes further:

• 🔌 Works with no COM port. On Windows, when the USB serial interface is bound to WinUSB (Google's ADB driver) and no COMx exists, it talks to the Flipper directly over the raw USB bulk endpoints via pyusb/libusb — no admin, no driver change. On macOS/Linux it uses the native serial device automatically. Transport is auto-selected: real serial port first, raw USB fallback.

• 🛠️ Build & deploy your own apps (FAPs) over USB. Scaffold → build with ufbt → upload to the SD card and launch — all over USB, no COM port required.

• 📸 Screenshots + reliable virtual buttons. Capture the 128×64 framebuffer as a PNG, and send PRESS → SHORT/LONG → RELEASE button sequences that actually register.

• 🧰 35 tools covering device info, power telemetry, SD-card storage (md5-verified binary transfer), Sub-GHz, NFC, RFID, Infrared (+ universal remotes), GPIO, I²C, iButton, LED, vibro, app control, and a raw CLI passthrough for everything else.

Built and verified live against a real Flipper Zero (firmware 1.4.3) on macOS and Windows.

Related MCP server: Flipper Zero MCP Server

Install (30 seconds)

# Run instantly, no install (recommended, once published to PyPI):
uvx flipper-mcp

# or with pip:
pip install flipper-mcp

Register with Claude Code

After pip install flipper-mcp (or using uvx), register the server once at user scope.

macOS / Linux:

claude mcp add --transport stdio --scope user \
  --env FLIPPER_TRANSPORT=auto \
  flipper -- flipper-mcp

Windows (PowerShell):

claude mcp add --transport stdio --scope user `
  --env FLIPPER_TRANSPORT=auto `
  flipper -- flipper-mcp

Then check /mcp inside Claude Code. Environment overrides:

macOS/Linux: the Flipper appears automatically as /dev/tty.usbmodemflip_* (macOS) or /dev/ttyACM* (Linux). Close qFlipper first — only one program can hold the port at a time. Windows: if no COMx exists, the raw WinUSB transport is used automatically. See docs/setup.md for the full per-OS guide.

Tools (35)

Build your own app (FAP)

fap_scaffold("my_app")   # ufbt create -> apps/my_app/
# edit apps/my_app/my_app.c + application.fam
fap_deploy("my_app")     # ufbt build -> upload to /ext/apps/<category>/ -> launch

ufbt (the build) needs no device; deploying goes over USB via the protobuf RPC storage upload, so no COM port is required. A worked example lives in examples/mcp_demo/ — a small counter app built and launched on-device during development.

How it works

flipper-mcp drives the Flipper's text serial CLI and its protobuf RPC over a single USB byte stream. It auto-selects the transport (real serial port → raw WinUSB), decodes the column-major framebuffer into PNGs, and chains length-delimited RPC frames for binary-safe, md5-verified file transfer. Verified protocol notes live in docs/research/.

Safety & legality

⚠️ Radio-transmit tools (flipper_subghz_tx_file, flipper_ir_send, flipper_ir_universal) affect real RF hardware and spectrum. Only transmit on frequencies and hardware you are legally authorized to use. You are responsible for complying with your local regulations.

Author

Made by Yair Hernández (@yairhdz24).

Licensed under the MIT License © 2026 Yair Hernández.

Contributions welcome — see CONTRIBUTING.md.