Skip to main content
Glama
Sign In
flipper-mcp

flipper-mcp

by yairhdz24
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

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.

PyPI Python License: MIT CI

flipper-mcp demo

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:

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.

Available Tools

35 tools
fap_buildA

Build a FAP in apps/ with ufbt. Returns build success, log tail, and the produced .fap path.

Inputs: appid (required).

fap_deployA

Build a FAP and deploy it to the Flipper over USB (upload to /ext/apps// and launch it). No COM port required.

Inputs: appid (required).

fap_scaffoldA

Scaffold a new Flipper app (FAP) with ufbt into the project's apps/ folder. appid must be lowercase letters/digits/underscore.

Inputs: appid (required).

flipper_app_exitA

Ask the currently running app to exit, returning to the desktop.

Inputs: no named parameters. Returns: result

flipper_app_startA

Launch an app by name (e.g. 'Sub-GHz', 'NFC', 'Storage') or by full .fap path. args is optional (e.g. a file to open).

Inputs: name (required), args. Returns: result

flipper_cliA

Run any Flipper CLI command and return its text output.

Examples: "help", "info device", "top", "free", "loader list", "storage list /ext", "gpio read PC0", "led g 255". Streaming commands (log, subghz rx, ir rx) will be cut off at the timeout — use flipper_cli_stream for those instead.

Inputs: command (required), timeout_seconds. Returns: result

flipper_cli_streamA

Run a streaming CLI command for a fixed duration, then stop it (Ctrl+C) and return what it printed.

Use for commands that stream until interrupted: "log", "subghz rx 433920000 0", "ir rx", "input dump".

Inputs: command (required), seconds. Returns: result

flipper_connectA

Open the connection to the Flipper (auto-selects a serial/COM port on any OS, or the raw WinUSB path on Windows when no port exists). Returns connection status.

Inputs: no named parameters.

flipper_deleteA

Delete a file or directory on the Flipper. Use recursive=true for non-empty directories.

Inputs: path (required), recursive. Returns: result

flipper_device_infoA

Get hardware/firmware details (model, name, region, firmware version, radio stack, BLE MAC, ...).

Inputs: no named parameters.

flipper_disconnectA

Close the connection to the Flipper, releasing the USB/serial handle.

Inputs: no named parameters. Returns: result

flipper_find_my_flipperA

Play an audiovisual alert (sound + backlight + vibro) to locate the device.

Inputs: no named parameters. Returns: result

flipper_gpioA

Control a GPIO pin. action: mode|set|read. pin: e.g. PC0, PC1, PC3, PB2, PB3, PA4, PA6, PA7. For mode/set, value 0/1.

Inputs: pin (required), action (required), value. Returns: result

flipper_ir_sendB

Transmit an infrared signal. protocol e.g. NEC, NECext, Samsung32, RC5, RC6, SIRC. address and command are hex (e.g. 0x04, 0x08).

Inputs: address (required), command (required), protocol (required). Returns: result

flipper_ir_universalA

Send a signal from a built-in universal IR remote. remote: tv, ac, audio, projector. Use flipper_cli('ir universal list tv') to list signals (e.g. Power, Vol_up, Mute).

Inputs: remote (required), signal (required). Returns: result

flipper_ledA

Set an onboard LED channel. channel: r, g, b (RGB) or bl (display backlight). value: 0-255.

Inputs: value (required), channel (required). Returns: result

flipper_list_appsA

List apps available to the loader (installed FAPs and built-in settings apps).

Inputs: no named parameters. Returns: result

flipper_list_dirA

List files and directories at a path (use /ext for SD card, /int for internal flash).

Inputs: path, include_md5.

flipper_mkdirC

Create a directory on the Flipper.

Inputs: path (required). Returns: result

flipper_pingA

Round-trip liveness check over protobuf RPC. Returns the echoed payload.

Inputs: no named parameters. Returns: result

flipper_power_infoA

Get battery/charging telemetry: charge level %, voltage, current, temperature, health, capacity.

Inputs: no named parameters.

flipper_pressA

Send a virtual button press. key: UP, DOWN, LEFT, RIGHT, OK, BACK. type: SHORT, LONG, PRESS, RELEASE.

Inputs: key (required), type. Returns: result

flipper_read_fileA

Read a file from the Flipper. Text is returned decoded; set binary=true to get base64.

Inputs: path (required), binary. Returns: result

flipper_rebootA

Reboot the Flipper. mode: OS (normal), DFU (bootloader), UPDATE. The connection will drop.

Inputs: mode. Returns: result

flipper_renameB

Rename or move a file/directory on the Flipper.

Inputs: new_path (required), old_path (required). Returns: result

flipper_screenshotA

Capture the Flipper's current screen (128x64) as a PNG image.

Inputs: no named parameters.

flipper_statA

Get type and size of a file or directory on the Flipper.

Inputs: path (required).

flipper_statusA

Report how the Flipper can be reached (serial ports on macOS/Linux/Windows, plus the WinUSB fallback) and whether it is connected. Does not open a connection.

Inputs: no named parameters.

flipper_storage_spaceA

Get total and free bytes for the /ext (SD) or /int (flash) filesystem.

Inputs: path.

flipper_subghz_rxA

Listen for Sub-GHz signals on a frequency (Hz) for a few seconds and return decoded output. Common: 433920000, 315000000, 868350000.

Inputs: seconds, frequency. Returns: result

flipper_subghz_tx_fileA

Transmit a saved Sub-GHz capture (.sub file on the SD card). WARNING: transmits on real RF — only use legal frequencies you are authorized to transmit on.

Inputs: path (required), repeat. Returns: result

flipper_upload_fileA

Upload a local file from this computer to a path on the Flipper's SD card; verifies md5.

Inputs: dest_path (required), local_path (required).

flipper_uptimeB

Get the Flipper's uptime since last boot.

Inputs: no named parameters. Returns: result

flipper_vibroA

Turn the vibration motor on or off.

Inputs: on (required). Returns: result

flipper_write_fileA

Write content to a file on the Flipper (overwrites). Returns the device-side md5. Set is_base64=true for binary content.

Inputs: path (required), content (required), is_base64. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 35 tools

    Disambiguation5/5

    Each tool targets a distinct capability: connection, status, info, CLI, file operations, UI control, hardware, RF, and app management are clearly separated. Even flipper_cli and flipper_cli_stream are well-differentiated by their streaming vs. non-streaming behavior.

    Naming Consistency4/5

    All tools use snake_case and are mostly descriptive with a verb_noun pattern (e.g., flipper_list_dir, flipper_read_file). However, the fap_* prefix for development tools deviates from the general flipper_* prefix, and a few names are nouns rather than verbs (e.g., flipper_led, flipper_vibro).

    Tool Count2/5

    At 35 tools, the server is over-scoped for an MCP server. Many granular tools (e.g., flipper_led, flipper_vibro, flipper_gpio) could be consolidated, and the count exceeds the typical range for a focused integration.

    Completeness4/5

    The tool set covers a broad range of Flipper Zero operations: connection, system info, filesystem management, CLI access, UI control, hardware peripherals, RF operations, app lifecycle, and FAP development. Minor gaps like file copy or NFC-specific operations are workarounds via flipper_cli.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • flipper-mcp-bridge

      dudebot
      F
      license
      A
      quality
      D
      maintenance
      An MCP server that exposes a USB-connected Flipper Zero device as tools for controlling infrared devices. It enables listing, parsing, and transmitting IR signals from saved files and built-in universal remotes.
      10
      -

    • Flipper Zero MCP Server

      busse
      A
      license
      Not graded
      quality
      D
      maintenance
      Modular MCP server for interacting with a Flipper Zero from MCP-capable clients (including Claude Desktop). Supports system info, BadUSB scripts, and music playback over USB or WiFi.
      36
      MIT