Skip to main content
Glama

flipper-zero-mcp

A small MCP server that lets an AI agent (Claude Code, Claude Desktop, or any MCP client) drive a Flipper Zero over USB: press buttons, see the screen, run CLI commands, manage files, and capture radio/IR/RFID input.

It is a small, dependency-light Python package. No custom firmware, no companion app on the Flipper, no extra hardware.

Screenshot returned by flipper_screenshot

What it can do

  • See and control the screen — flipper_screenshot returns the display as a PNG; flipper_navigate and flipper_press send button presses and can return the resulting screen in the same call.

  • Run anything on the CLI — flipper_run_cli for normal commands, flipper_listen for commands that run until interrupted (subghz rx, ir rx, rfid read, ...).

  • Manage files — list, read, download, upload (MD5-verified), mkdir, delete.

  • Launch and close apps, run JavaScript on the device, write and run BadUSB scripts, transmit saved Sub-GHz files, set the LED and vibration motor.

  • Diagnose itself — flipper_status reports whether the Flipper is connected, the port is free, the CLI answers and the screen can be captured.

  • Survey before acting — flipper_index gives one-call structural context (firmware, radio, SD tree); flipper_find locates files by name.

  • Remember what it learns — a per-user, git-ignored knowledge/ folder lets the agent save and reuse task notes with flipper_kb_save / _list / _read / _search, so similar future tasks start from prior work instead of scratch.

Full list: docs/TOOLS.md.

Related MCP server: pico-bay

Requirements

  • Flipper Zero connected by USB

  • Python 3.10+

  • pip install -r requirements.txt (mcp, pyserial)

Tested on Windows 11 with Momentum firmware (mntm-012). It uses only the standard Flipper CLI and RPC, so other firmware and operating systems should work, but they have not been tested.

Install

git clone https://github.com/girishalpha/flipper-zero-mcp.git
cd flipper-zero-mcp
pip install -r requirements.txt        # or: pip install -e .  (adds the `flipper-mcp` command)
python -m flipper_mcp --selftest

The self-test prints the device info and SD card status, then self-test OK.

You can start the server three equivalent ways:

python -m flipper_mcp          # preferred
flipper-mcp                    # after `pip install -e .`
python flipper_mcp_server.py   # legacy entry point, still supported

Claude Code

claude mcp add flipper -- python /full/path/to/flipper_mcp_server.py

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "flipper": {
      "command": "python",
      "args": ["/full/path/to/flipper_mcp_server.py"]
    }
  }
}

Configuration

The serial port is found automatically by USB ID (0483:5740). To override it, set the FLIPPER_PORT environment variable (for example COM10 or /dev/ttyACM0).

Example

Ask the agent something like:

Open the Infrared app on my Flipper and show me the screen.

It will typically call flipper_status, then flipper_loader_open, then flipper_screenshot, and use flipper_navigate(..., screenshot=True) to move through menus while watching the result.

How it works

  • The server opens the serial port for each tool call and closes it again, so it never blocks qFlipper or other tools between calls.

  • Commands go through the Flipper's text CLI at 230400 baud.

  • Screenshots use the Flipper's protobuf RPC: the server starts an RPC session, requests the screen stream, takes one 128x64 frame, stops the session and encodes the frame as a PNG. The few protobuf messages involved are encoded by hand, so no generated protobuf code is needed.

Project layout

The server is split into a small helper core and one module per task domain, so each capability has an obvious home and new ones are easy to add:

flipper_mcp/
├── app.py            shared FastMCP instance
├── server.py         wires the tools together + main()/--selftest
├── transport.py      Flipper serial session + port detection   ┐
├── protocol.py       hand-rolled protobuf decode                ├ helper core
├── imaging.py        framebuffer → PNG                          │
├── knowledge_base.py task-knowledge file helpers                ┘
└── tools/            one file per task domain
    ├── device.py   info, raw CLI, status, power, LED/vibro, listen
    ├── storage.py  list/read/download/upload/mkdir/delete
    ├── gui.py      press, navigate, unlock, screenshot
    ├── apps.py     loader open/close, launch .fap, run JS
    ├── survey.py   index, find
    ├── knowledge.py  kb_list/read/search/save
    ├── subghz.py   Sub-GHz transmit
    └── badusb.py   author + run DuckyScript

flipper_mcp_server.py at the repo root is a thin compatibility shim that keeps older MCP configs working. To add a new task domain (e.g. NFC, RFID, IR, GPIO), drop a tools/<name>.py that registers its @mcp.tool() functions and add "<name>" to _MODULES in tools/__init__.py.

The knowledge/ folder is per-user local memory: only its README.md and .gitignore are committed — saved notes are git-ignored and never pushed.

Things to know

  • A locked Flipper refuses screenshots. On Momentum, RPC is blocked while the device is keypad- or PIN-locked. flipper_unlock clears a keypad lock.

  • Only one program can hold the serial port. Close qFlipper and any lab.flipper.net browser tab before using this server.

  • More in docs/TROUBLESHOOTING.md.

Responsible use

This server gives an AI agent real control of a radio and HID device. Transmit only on frequencies that are legal where you are, and only at devices you own. Run BadUSB scripts only on computers you own or are authorised to test.

License

MIT — see LICENSE.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to control and analyze RFID hardware through natural language: read, crack, emulate, and clone cards via MCP tools, with safety gates, offline dump analysis, and a host-side card library.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to manage MicroPython and CircuitPython boards over USB, including listing boards, browsing and editing files, running Python code, resetting boards, and installing firmware.
      14
      10
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes 238 schema-typed tools over streamable-HTTP MCP that let a client drive a Flipper Zero, an AWOK Biscuit (ESP32-C5) and an ESP32 Marauder — scanning, screen mirroring, storage, and other device operations — from natural-language or direct tool calls. Transmit/attack tools stay behind an explicit human confirmation gate.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to see and control Android devices over ADB and scrcpy—taking screenshots, tapping, swiping, typing, launching apps, inspecting UI elements, transferring files, streaming video/audio, and running shell commands. It uses scrcpy's control protocol for fast input and near-instant screenshots, with ADB fallback when scrcpy is unavailable.
      392 npm
      MIT