convez.ai
MCP Server
millsymills-com

flipperzero-mcp

millsymills-com/flipperzero-mcp

Ver no GitHub
BomPluginScore · de 0 a 100

Modular MCP server for the Flipper Zero (USB + WiFi protobuf RPC)

Instalação

$npx convez-ai millsymills-com/flipperzero-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
1
Acompanhando
0
Saúde
75%
Último commit
há 6 dias
Versão
—
Issues abertas
9
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

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, 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.

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, 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.

VariableDefaultDescription
FLIPPER_TRANSPORTautoTransport selection: auto, usb, or wifi.
FLIPPER_USB_PORT(auto-detect)Serial device path (e.g. /dev/ttyACM0). Unset = auto-detect.
FLIPPER_USB_BAUDRATE115200USB serial baud rate.
FLIPPER_WIFI_HOST(unset)Dev board IP/hostname. Required for WiFi.
FLIPPER_WIFI_PORT8080Dev board TCP port.
FLIPPER_ENABLE_WRITE_TOOLSfalseServer-side gate for device-mutating storage writes (fs_push, fs_mkdir). Off blocks them.
FLIPPER_ENABLE_TX_TOOLSfalseServer-side gate for transmit/destructive CLI commands. Off blocks them regardless of the per-call flag.
FLIPPER_ENABLE_FIRMWARE_FLASHfalseServer-side gate for flipperzero_firmware_install. Requires FLIPPER_ENABLE_WRITE_TOOLS=true as well.
FLIPPER_DEBUGfalseEnable verbose debug logging.
FLIPPER_FORCE_START_RPC_SESSIONfalseAdvanced/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

ToolDescription
flipperzero_connection_healthReport connection health (connected, transport, RPC responsiveness, last error). Optionally pings RPC.
flipperzero_connection_reconnectDisconnect and reconnect, then report updated health.
flipperzero_system_infoReturn device info (name, hardware, firmware), transport, and SD-card availability.
flipperzero_system_power_infoReturn firmware-reported power/battery key-value pairs.
flipperzero_system_protobuf_versionReturn the device protobuf RPC major/minor version.
flipperzero_system_datetimeReturn the device date/time fields.
flipperzero_fs_infoReturn storage capacity information for a path such as /ext.
flipperzero_fs_statReturn metadata for a device file or directory.
flipperzero_fs_timestampReturn the device timestamp for a file or directory.
flipperzero_fs_listList a device directory; returns typed entries (name, type, size, optional md5).
flipperzero_fs_mkdirCreate a directory on the device storage.
flipperzero_fs_deleteDelete a file or directory on the device storage.
flipperzero_fs_renameRename or move a device file/directory.
flipperzero_fs_pushUpload a local file to the device and verify integrity against the device MD5.
flipperzero_fs_pullDownload a device file to the host and verify integrity against the device MD5.
flipperzero_app_startStart a Flipper application via RPC; gated behind FLIPPER_ENABLE_WRITE_TOOLS.
flipperzero_cli_execRun one Flipper CLI command and return its output, completion flag, and risk classification.
flipperzero_firmware_installFlash 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 <github_url> 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/<pkg>/ 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.

Ver o original no GitHub

Bom para

Relacionados