Flipperzero Mcp

flipperzero-mcp

An MCP server for the Flipper Zero. It speaks protobuf RPC to a Flipper over USB or over WiFi (via an ESP32 WiFi Dev Board) and exposes connection and system tools to MCP clients such as Claude Desktop.

Status

Stage: S2 (wrapped). The server runs over stdio with read tools (connection health, reconnect, system info/power/datetime/protobuf-version/ping/property, device reads app_lock_status/app_get_error/desktop_is_locked/gpio_read, typed USB CLI reads core_status/fs_tree/loader_list/i2c_scan, and storage reads fs_info, fs_stat, fs_timestamp, fs_list, fs_pull) and write tools (fs_mkdir, fs_delete, fs_rename, fs_push, app_start, cli_exec). Device-mutating storage/app operations are gated behind FLIPPER_ENABLE_WRITE_TOOLS and transmit/destructive CLI commands behind FLIPPER_ENABLE_TX_TOOLS, both default-off. CI runs lint and tests on the committed lockfile. The /flipper-install flagship and live integration suite are the S3 climb tracked in the public-launch issues (#37 umbrella). The flagship was validated end-to-end on hardware (clone → ufbt build → md5-verified push → launch) — see [docs/proof/2026-06-10-flipper-install.md](docs/proof/2026-06-10-flipper-install.md).

Features

• stdio MCP server (FastMCP).
• Two transports for the Flipper protobuf RPC link:
• USB: serial CDC, with CLI to RPC session switching.
• WiFi: TCP to an ESP32 dev board running the TCP-to-UART bridge firmware.
• auto transport selection: USB first, WiFi fallback only when a WiFi host is set.
• Tools: connection health/reconnect, system info/power/datetime/protobuf-version/ping/property, device reads (app lock/error, desktop lock, gpio), typed USB CLI reads (core status, storage tree, loader list, i2c scan), storage info/stat/timestamp/list/push/pull/mkdir/delete/rename, app start, and USB CLI exec.

Install

uv sync
# or
pip install -e .

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "flipper-zero": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/flipperzero-mcp", "flipperzero-mcp"],
      "env": { "FLIPPER_TRANSPORT": "auto" }
    }
  }
}

Configuration

The server reads FLIPPER_* environment variables (or a local .env). See src/flipperzero_mcp/config.py for the authoritative definitions.

| Variable | Default | Description | |---|---|---| | FLIPPER_TRANSPORT | auto | Transport selection: auto, usb, or wifi. | | FLIPPER_USB_PORT | (auto-detect) | Serial device path (e.g. /dev/ttyACM0). Unset = auto-detect. | | FLIPPER_USB_BAUDRATE | 115200 | USB serial baud rate. | | FLIPPER_WIFI_HOST | (unset) | Dev board IP/hostname. Required for WiFi. | | FLIPPER_WIFI_PORT | 8080 | Dev board TCP port. | | FLIPPER_ENABLE_WRITE_TOOLS | false | Server-side gate for device-mutating storage writes (fs_push, fs_mkdir). Off blocks them. | | FLIPPER_ENABLE_TX_TOOLS | false | Server-side gate for transmit/destructive CLI commands. Off blocks them regardless of the per-call flag. | | FLIPPER_ENABLE_FIRMWARE_FLASH | false | Server-side gate for flipperzero_firmware_install. Requires FLIPPER_ENABLE_WRITE_TOOLS=true as well. | | FLIPPER_DEBUG | false | Enable verbose debug logging. | | FLIPPER_FORCE_START_RPC_SESSION | false | Advanced/debug: force start_rpc_session even when probing suggests RPC mode is already active. |

With FLIPPER_TRANSPORT=auto (the default), the server tries USB first and only falls back to WiFi when FLIPPER_WIFI_HOST is set.

Available tools

| Tool | Description | |---|---| | flipperzero_connection_health | Report connection health (connected, transport, RPC responsiveness, last error). Optionally pings RPC. | | flipperzero_connection_reconnect | Disconnect and reconnect, then report updated health. | | flipperzero_system_info | Return device info (name, hardware, firmware), transport, and SD-card availability. | | flipperzero_system_power_info | Return firmware-reported power/battery key-value pairs. | | flipperzero_system_protobuf_version | Return the device protobuf RPC major/minor version. | | flipperzero_system_datetime | Return the device date/time fields. | | flipperzero_fs_info | Return storage capacity information for a path such as /ext. | | flipperzero_fs_stat | Return metadata for a device file or directory. | | flipperzero_fs_timestamp | Return the device timestamp for a file or directory. | | flipperzero_fs_list | List a device directory; returns typed entries (name, type, size, optional md5). | | flipperzero_fs_mkdir | Create a directory on the device storage. | | flipperzero_fs_delete | Delete a file or directory on the device storage. | | flipperzero_fs_rename | Rename or move a device file/directory. | | flipperzero_fs_push | Upload a local file to the device and verify integrity against the device MD5. | | flipperzero_fs_pull | Download a device file to the host and verify integrity against the device MD5. | | flipperzero_app_start | Start a Flipper application via RPC; gated behind FLIPPER_ENABLE_WRITE_TOOLS. | | flipperzero_cli_exec | Run one Flipper CLI command and return its output, completion flag, and risk classification. | | flipperzero_firmware_install | Flash a firmware bundle to the device via USB. Destructive; gated by FLIPPER_ENABLE_FIRMWARE_FLASH=true + FLIPPER_ENABLE_WRITE_TOOLS=true + a confirm token matching the device name. |

CLI exec is USB-only; transmit/destructive commands require both FLIPPER_ENABLE_TX_TOOLS=true on the server and i_accept_responsibility=true on the call.

Scope & limitations

• CLI is USB-only. flipperzero_cli_exec needs the Flipper text CLI shell,

which only the USB CDC link carries. Over the WiFi bridge (protobuf-only) it returns a clear "CLI text mode unavailable over WiFi bridge" error.

• No streaming/interactive commands. Commands that never return to the >:

prompt (e.g. subghz rx, ir rx, log) time out with completed=false and partial output. Commands that expect interactive input are unsupported.

• Transmit/destructive commands are double-gated. Both FLIPPER_ENABLE_TX_TOOLS=true

(operator, server-side) and i_accept_responsibility=true (per call) are required; either missing refuses the command. The risk classifier is an advisory ordered-prefix list that fails open — the env flag is the real boundary. Radio transmission is subject to local regulations; you are responsible for legal use.

• Device writes are gated. Storage/app mutations need FLIPPER_ENABLE_WRITE_TOOLS=true,

default-off.

• Distribution is git-clone + uv. No PyPI package at this stage.
• WiFi needs the ESP32 bridge running the harvested TCP↔UART firmware; that

firmware is not built in CI.

Resources & prompts

Bundled MCP resources:

• flipper://reference/cli
• flipper://reference/connection
• flipper://reference/filesystem
• flipper://reference/system
• flipper://workflow/install-app
• flipper://workflow/transfer-files
• flipper://workflow/flash-esp32
• flipper://workflow/capture-replay

Prompts:

• manage_flipper
• troubleshoot_connection
• flipper_install — the /flipper-install flagship: clone → ufbt

build matched to the device firmware → md5-verified push → launch.

• flipper_doctor — the /flipper-doctor end-to-end connection/device diagnostic sweep.

Development

uv sync --extra dev              # install runtime + dev deps into .venv
uv run pytest -m "not integration"   # default suite (no hardware required)
uv run ruff check && uv run ruff format --check
uv run ty check

Integration tests (-m integration) need a real Flipper over USB or WiFi and are local-only. See CLAUDE.md for project conventions and CONTRIBUTING.md.

Firmware

Supported firmware. The server supports both Official firmware (channels release, release-candidate, development; tested on 1.4.x) and Momentum (mntm-012). The protobuf RPC layer is firmware-agnostic. The golden test fixtures (tests/golden/) were captured on Momentum mntm-012 (protobuf RPC 0.25, build 2025-12-31). CLI text output and command availability can differ between firmware flavors — re-validate and re-record fixtures (make record-fixtures) after a firmware change.

The protobuf runtime is pinned to protobuf==6.33.5 (see CLAUDE.md). flipperzero_system_info returns a firmware block: {flavor, version, origin_fork, origin_git, target}.

Flashing firmware (flipperzero_firmware_install). The tool pushes a firmware bundle to /ext/update// on the device and reboots into the on-device updater. The source is either a local .tgz path or {flavor, channel, version} for auto-download (downloads Official from update.flipperzero.one or Momentum from GitHub releases).

• Integrity. Bundles are verified by sha256 before transfer — Official via

the per-file sha256 in directory.json; Momentum via the GitHub release asset digest. This is integrity verification over HTTPS, not GPG-signed provenance.

• USB-only. Flashing requires USB. The device reboots into the on-device

updater; the WiFi bridge cannot survive that reboot.

• Gating. Requires FLIPPER_ENABLE_WRITE_TOOLS=true AND

FLIPPER_ENABLE_FIRMWARE_FLASH=true (both default-off), plus a confirm argument that must equal the connected device's name.

• Recovery. If flashing fails, the device enters DFU mode. Use

qFlipper to recover. Momentum has no automatic OTA fallback.

ESP32 WiFi bridge. WiFi transport requires an ESP32 WiFi Dev Board running the TCP↔UART bridge firmware shipped in firmware/tcp_uart_bridge/. See that directory's README.md for ESP-IDF build/flash instructions and docs/wifi_dev_board.md for the end-to-end setup guide. The firmware is harvested as-is and is not built in CI.

Attribution

Portions of this project (transport layer, protobuf RPC implementation, and the ESP32 WiFi-bridge firmware) are harvested from busse/flipperzero-mcp under the MIT License. See NOTICE for details.

License

MIT. See LICENSE.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: millsymills-com
• Source: millsymills-com/flipperzero-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.