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.

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:

Variable	Values	Meaning
FLIPPER_TRANSPORT	auto (default), serial, usb	Force a transport, or auto-select serial → raw USB
FLIPPER_COM_PORT	e.g. COM5, /dev/tty.usbmodemflip_xxxx	Force a specific serial port

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)

Domain	Tools
Connection	flipper_status, flipper_connect, flipper_disconnect
System / info	flipper_device_info, flipper_power_info, flipper_uptime, flipper_ping, flipper_reboot, flipper_find_my_flipper
CLI	flipper_cli, flipper_cli_stream
Storage (SD / flash)	flipper_list_dir, flipper_stat, flipper_storage_space, flipper_read_file, flipper_write_file, flipper_upload_file, flipper_mkdir, flipper_delete, flipper_rename
GUI	flipper_screenshot, flipper_press
Radio / subsystems	flipper_led, flipper_vibro, flipper_gpio, flipper_ir_send, flipper_ir_universal, flipper_subghz_tx_file, flipper_subghz_rx
Apps	flipper_list_apps, flipper_app_start, flipper_app_exit
FAP development	fap_scaffold, fap_build, fap_deploy

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.