🐬 clipper

Drive your Flipper Zero with natural language.

clipper is an MCP server that exposes a Flipper Zero over USB serial as native tools for Claude Code (and any other MCP client) — read GPIO, capture & replay Sub-GHz, scan NFC/RFID, emulate cards, browse the device filesystem, recover MIFARE Classic keys, and more. No model API credits required.

---

✨ What it looks like

Once it's connected, you just ask — the model picks the right tool:

💬 "Is my Flipper connected, and what's the battery?" → flipper_state → Connected — Pelima on mntm-012, battery 80%.

💬 "Capture Sub-GHz on 433.92 MHz for 10 seconds and tell me how many packets you saw." → flipper_subghz_rx → Captured 3 packets in 10s.

💬 "List the apps on the device, then open the NFC app." → flipper_loader_list → flipper_loader_open

Every capability is a discrete, schema-validated MCP tool, so you stay in plain English.

🚀 Quickstart

Requirements: Python 3.12+, uv, and a Flipper Zero on Momentum firmware connected over USB.

# 1. Install (handles the macOS uv/.pth quirks for you)
git clone https://github.com/Realgagenichols/clipper.git
cd clipper
make sync

# 2. Register with Claude Code
claude mcp add clipper -- /absolute/path/to/clipper/scripts/clipper-mcp-stdio.sh

Then start a Claude Code session and ask it to "use flipper_state to check the battery." That's it.

To enable the transmit / emulate / state-changing tools, add the safety gate (see Safety & responsible use):

claude mcp add clipper -- env CLIPPER_SAFETY=1 /absolute/path/to/clipper/scripts/clipper-mcp-stdio.sh

The server starts fine with no device attached — only tools that touch the serial port report a disconnect, and it auto-reconnects when you plug back in.

🧰 Tools

32 tools, grouped by subsystem. ⚡ = emissive (transmits RF/IR/USB) · 🔒 = state-changing. Both are blocked unless the safety gate is on.

Device & diagnostics

Tool	Description
flipper_state	Connection status, name, firmware, battery
flipper_uptime	Device uptime
flipper_datetime	Read the device clock (RTC)
flipper_diagnostics	Heap + task diagnostics
flipper_power	Power off / reboot / reboot2dfu	🔒
flipper_power_otg	Toggle external 5V OTG output	🔒

GPIO

Tool	Description
flipper_gpio_read	Read a GPIO pin level
flipper_gpio_write	Write a GPIO pin level

Infrared

Tool	Description
flipper_ir_rx	Receive IR signals (timeout-based)
flipper_ir_tx	Transmit an IR signal	⚡

Sub-GHz

Tool	Description
flipper_subghz_rx	Capture Sub-GHz packets (timeout-based)
flipper_subghz_tx	Transmit a Sub-GHz signal	⚡
flipper_subghz_tx_from_file	Replay a saved .sub file	⚡

NFC · RFID · iButton

Tool	Description
flipper_nfc_read	Read an NFC tag
flipper_rfid_read	Read a 125 kHz RFID card
flipper_rfid_emulate	Emulate a 125 kHz RFID card (timeout-based)	⚡
flipper_ibutton_emulate	Emulate an iButton key (timeout-based)	⚡
flipper_mfkey_crack	Recover MIFARE Classic keys (mfkey32v2)	🔒

USB / HID

Tool	Description
flipper_badusb_run	Run a DuckyScript payload	⚡

Storage

Tool	Description
flipper_storage_info	Filesystem space info
flipper_storage_list	List a directory
flipper_storage_stat	Stat a path
flipper_storage_md5sum	MD5 hash of a file on the device
flipper_storage_read	Read a file (optionally download to host)
flipper_storage_write	Write a file to the device	🔒

Apps & on-device feedback

Tool	Description
flipper_loader_open	Open an app on the device
flipper_loader_list	List available apps
flipper_loader_info	Report the running app
flipper_loader_close	Close the running app
flipper_led_set	Set the on-device LED state
flipper_led_color	Set the on-device LED color
flipper_vibro_set	Toggle the vibration motor

🔐 Safety & responsible use

Tools that transmit (IR/Sub-GHz TX, file replay, BadUSB), emulate a credential (RFID/iButton), or change device state (storage write, key recovery, power off/reboot, 5V OTG) are blocked by default. Unlock them with:

CLIPPER_SAFETY=1

• Audit trail. Every gated invocation — allowed or denied — is appended to ~/.clipper/audit.log (override with CLIPPER_AUDIT_PATH). It records the action, transport, outcome, and parameters, and never logs secrets (credential data like RFID/iButton keys is redacted).
• Frequency allow-list. Sub-GHz transmits are restricted to an allow-list (override with CLIPPER_SGHZ_ALLOWED_MHZ). Receiving is unrestricted.
• Use it lawfully. clipper can transmit RF and emulate access credentials. Only use it on hardware, signals, and credentials you own or are explicitly authorized to test. You are responsible for complying with local radio and computer-misuse laws.

⚙️ Configuration

All configuration is via environment variables:

Variable	Default	Purpose
CLIPPER_SAFETY	unset	Set to 1 to unlock emissive / state-changing tools
CLIPPER_FLIPPER_PORT	auto-detect	Serial port to use (e.g. /dev/cu.usbmodemflip_Xxxx)
CLIPPER_SGHZ_ALLOWED_MHZ	built-in list	Comma-separated allowed Sub-GHz TX frequencies (MHz)
CLIPPER_DOWNLOAD_DIR	~/.clipper/flipper-files	Where flipper_storage_read downloads land
CLIPPER_AUDIT_PATH	~/.clipper/audit.log	Audit log location
CLIPPER_LOG_LEVEL	INFO	Log level (logs go to stderr; stdout is the JSON-RPC stream)

CLIPPER_ALLOW_EMIT=1 is honored as a deprecated alias for CLIPPER_SAFETY=1.

🛠️ How it works

Claude / MCP client  ──stdio (JSON-RPC)──▶  clipper MCP server
                                                  │
                                          action registry  ── every action = one MCP tool
                                                  │
                                   FlipperConnection (single locked serial port)
                                          │                         │
                                    text CLI commands         binary RPC (protobuf)
                                                  ▼
                                            Flipper Zero

A single FlipperConnection owns the serial port behind an async lock, so concurrent tool calls are serialized cleanly. Most tools shell out to the Flipper's text CLI; binary-safe file transfer uses the RPC protobuf protocol. The connection drains the line to quiescence between operations and auto-recovers from device reboots / re-enumeration.

🧑‍💻 Development

make test    # run the full test suite
make lint    # ruff

# a single test file
UV_NO_EDITABLE=0 uv run pytest tests/test_mcp.py -v

Contributions welcome — please keep tools small and schema-validated, add tests for new behavior (TDD), and run make test && make lint before opening a PR.

🙏 Acknowledgements

• The Flipper Zero team and the Momentum firmware project.
• The Model Context Protocol.
• MIFARE Classic key recovery ports the Crypto1 / mfkey32v2 algorithm from the Flipper firmware and proxmark3 lineage.

📄 License

MIT © Gage Nichols