Skip to main content
Glama
pogorelov-labs

flipper-ble-mcp

by pogorelov-labs
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

flipper-ble-mcp 🐬📡

Drive a Flipper Zero wirelessly over Bluetooth LE from Claude — no USB cable — backed by a self-evolving knowledge base that makes every session faster than the last.

CI PyPI License: MIT Platform: macOS Python 3.11+ MCP

flipper-ble-mcp is three layers that form a loop:

  1. An MCP server (src/) — 38 tools that control a Flipper Zero over BLE: read device info & files, screenshot the screen, inject button presses, launch apps, app-driven Sub-GHz/IR transmit, GPIO, BadUSB, and a scheduled read-only health-watch.

  2. A skill (.claude/skills/flipper/) — the operating brain: an ORIENT → EXECUTE → CAPTURE loop, a routine index (task → KB doc → tools), verified menu maps, and safety gates.

  3. A knowledge base (the docs in this repo) — ships prebuilt with deep Flipper + toolkit knowledge the agent reads before acting and writes back to after (/flipper-learn).

read the KB  →  act via MCP  →  capture what you learned  →  KB grows  →  next session is faster

That last arrow is the point: instead of re-deriving how the device behaves each time, the agent accumulates expertise — and it ships with a big head start.

⚠️ macOS only (today). The Bluetooth work runs inside a small ad-hoc-signed .app that carries the macOS Bluetooth entitlement; the MCP process itself never touches BT. See Architecture.

⚠️ Dual-use tool. It can transmit RF/IR and inject USB keystrokes (BadUSB). Your own devices, authorized targets, and legal frequencies only. Every real action is human-approved per call. See SECURITY.md.

Why

LLM agents are great at reasoning and terrible at remembering what they learned last time. This project pairs real hardware control (an MCP server) with a knowledge base the agent both consumes and grows — so operating a Flipper gets faster and more reliable with use, and the knowledge is portable (it ships in the repo, not trapped in one chat).

Related MCP server: Lovense Cloud MCP

Demo

Demo GIF coming soon.

Architecture

Claude (Desktop / Code)
      │  MCP (stdio)
      ▼
flipper-ble MCP server  ──────────────┐   (never touches Bluetooth directly)
      │  token-authed Unix socket      │
      ▼                                │
resident daemon  (holds ONE BLE link)  │  runs inside FlipperBLE.app —
      │  Bluetooth LE                   │  the ad-hoc-signed bundle that carries
      ▼                                ┘  the macOS Bluetooth (TCC) entitlement
   Flipper Zero

A persistent daemon keeps a single BLE connection open (status/reads ~0.1–0.3 s, screenshot/press ~1.5 s; idle-disconnects to free the radio for your phone). The socket is 0600 + shared-token authed.

Install

Prerequisites: macOS, a Flipper Zero (Momentum / Unleashed / official firmware), Claude Code or Claude Desktop, Python 3.11+, and uv.

git clone https://github.com/pogorelov-labs/flipper-ble-mcp && cd flipper-ble-mcp
./app/build_app.sh            # builds + ad-hoc-signs FlipperBLE.app (one-time; no Apple Dev account)

Add the MCP server to Claude — claude mcp add flipper-ble -- uvx flipper-ble-mcp, or in your Claude Desktop config:

{
  "mcpServers": {
    "flipper-ble": { "command": "uvx", "args": ["flipper-ble-mcp"] }
  }
}

Then run Claude Code in this repo: the flipper skill + the KB are auto-discovered, so just ask — "what's my Flipper's battery?" / "screenshot my Flipper." (To use the skill outside the repo, copy .claude/skills/flipper/ and .claude/commands/flipper-learn.md into your ~/.claude/.)

The self-evolving knowledge base

  • Seed (this repo) — curated, general Flipper + toolkit knowledge. Indexed by llms.txt.

  • Local overlay (kb-local/, git-ignored) — where each install's new learnings land via /flipper-learn. The skill reads it alongside the seed; local entries win on conflict.

  • PR-back — broadly-useful learnings get promoted into the seed via pull request, so the community's collective experience compounds. Classification rule: .claude/skills/flipper/references/kb-map.md.

Tools

38 tools — full table + RPC mapping in resources/flipper-ble-control.md. Highlights: device_info, power_info, screenshot, press / press_sequence, storage_*, app_launch, transmit_subghz / transmit_infrared (gated), gpio_*, run_badusb (gated), healthwatch.

Safety & responsible use

See SECURITY.md: every action is human-approved per call; RF/IR/BadUSB is for your own authorized targets on legal bands; the health-watch is read-only and default-off; the agent is instructed never to autonomously transmit.

Contributing

See CONTRIBUTING.md — including how to PR a learned-KB entry back into the seed. House style for KB docs: CLAUDE.md.

License

MIT © 2026 Ruslan Pogorelov.

State: 70 content docs, ~102k words. The knowledge base below is generated from per-doc frontmatter — run python3 build-kb-index.py to rebuild; never hand-edit the block.

Index

Start here / Core

File

Status

What's in it

use-cases-model.md

✅

Scored data model — schema + 1–10 real-use rubric + 63 use-cases in ranked score bands.

01-architecture.md

✅

Hardware block map, STM32WB MCU, radios, software stack, SD layout, and full capability map.

legal-and-safety.md

✅

Dual-use ground rules — RF-transmit, cloning, HID, EMV reality, and a responsible-use checklist.

glossary.md

✅

One-line definitions of every term used across the KB, each linking to its deep-dive.

Dataset: use-cases.csv / use-cases.json — regenerate the JSON with python3 build-use-cases-json.py. UC-ID → docs map: uc-index.json.

Firmware

File

Status

What's in it

firmware/README.md

✅

Firmware comparison matrix, Xtreme to Momentum history, flashing/recovery, and legal/stability risks.

firmware/migration-xtreme-to-momentum.md

✅

Step-by-step — back up SD, flash Momentum, restore, re-enable add-ons, verify (frontier Stage 0).

firmware/momentum.md

✅

Feature-rich Xtreme successor — capabilities by domain plus an honest is-it-the-best verdict.

firmware/official.md

✅

Stock OFW from Flipper Devices — abilities, deliberate limits, and the sanctioned app catalog.

firmware/roguemaster.md

✅

Kitchen-sink, bleeding-edge custom firmware with the largest bundled app/game set and most crashes.

firmware/unleashed.md

✅

Unlocked, stable, RF-focused custom firmware — the oldest OFW fork, favored for serious Sub-GHz work.

Hardware & GPIO

File

Status

What's in it

hardware/README.md

✅

GPIO pinout, ADC/PWM/buses, power limits, and the Flipper's internal-radio front-end hardware.

hardware/esp32-firmware-comparison.md

✅

Bruce vs Ghost ESP vs Marauder — which firmware to flash on an ESP32 Flipper backpack.

hardware/esp32-marauder-module.md

✅

The ESP32-WROOM Marauder backpack hardware — GPIO 9-18 mount (3V3), the freeze fix, BOOT/RST buttons, dual-SD, flashing.

hardware/gpio-addons-current.md

✅

Current GPIO add-ons — DevBoard, VGM, Marauder/Ghost ESP, Mayhem, NRF24, CC1101, GPS, protoboards.

hardware/buying-guide.md

✅

Which GPIO add-on(s) to buy, by goal/persona, with a board-vs-persona comparison table.

hardware/addons-explained.md

✅

Plain-words use-cases + pros/cons for each Flipper GPIO add-on — GPS, NRF24, CC1101, BLE sniffer, thermal, geiger.

hardware/gpio-addons-potential.md

✅

DIY GPIO add-ons — I²C/SPI/UART sensors, displays, LoRa, BLE sniffer, logic analyzer, and design limits.

Capabilities (built-in feature deep-dives)

File

Status

What's in it

capabilities/badusb.md

✅

HID keystroke injection over USB (and BLE on CFW) — Ducky Script, layouts, OS targets, and blue-team defenses.

capabilities/ibutton.md

✅

Dallas / Cyfral / Metakom contact "touch" keys over 1-Wire — read, emulate, and clone to writable blanks.

capabilities/infrared.md

✅

Capture, store, and replay consumer IR; protocols, .ir format, universal remotes, and the Flipper-IRDB library.

capabilities/nfc-rfid.md

✅

Overview of the two card radios — LF 125 kHz RFID and HF 13.56 MHz NFC; deep dives live in cards/.

capabilities/sub-ghz.md

✅

CC1101 sub-1-GHz radio — bands, modulation/presets, on-device workflows, .sub format, protocol decoders.

Cards, NFC & RFID (deep-research sub-domain)

File

Status

What's in it

cards/README.md

✅

Hub: card taxonomy, security tiers, and the cards doc index

cards/cloning-matrix.md

✅

What's cloneable + how, magic cards, and a blanks list

cards/iclass-picopass.md

✅

iCLASS legacy vs SE/SEOS; the PicoPass app

cards/lf-125khz.md

✅

EM4100/HID Prox/Indala/AWID + T5577 cloning

cards/mifare.md

✅

MIFARE Classic/Ultralight/NTAG/DESFire + Crypto1 attacks

cards/nfc-theory.md

✅

RFID/NFC physics + ISO 14443/15693/18092 protocols

Wi-Fi (ESP32 Marauder add-on)

File

Status

What's in it

wifi/README.md

✅

Hub: Wi-Fi capability map — which use-case lives in which doc.

wifi/evil-portal.md

✅

Rogue-AP captive-portal credential harvesting.

wifi/marauder-mcp-scan.md

✅

Agent-driven AP scan — launch Marauder over the BLE MCP, run scanap, read the full network list from the SD log.

wifi/own-network-audit.md

✅

Runnable: audit your own PSK (capture, hcxtools, hashcat).

wifi/deauth.md

✅

Deauthentication: the 802.11 flaw and the PMF/802.11w defense.

wifi/recon-and-attacks.md

✅

Scan, sniff to PCAP, beacon spam, analyzer, wardrive, detect-deauth.

wifi/wpa-handshake-pmkid.md

✅

Capture the WPA 4-way handshake / PMKID and crack it offline with hashcat.

Bluetooth / BLE

File

Status

What's in it

bluetooth/README.md

✅

Hub for Bluetooth on this rig — Classic vs BLE, and the BLE use-case map across the sub-domain docs.

bluetooth/airtag-tracker-detection.md

✅

How Find My works, anti-stalking tracker detection, rig limits, and FindMy Flipper as the inverse emulator.

bluetooth/ble-sniffer-addon.md

✅

Real BLE connection capture via nRF52840/nRF Sniffer or Sniffle, plus crackle for LE Legacy pairings.

bluetooth/ble-spam.md

✅

Advertising-flood pairing popups (Sour Apple/Fast Pair/Swift Pair); the iOS 17.2 story; nuisance, not a hack.

bluetooth/classic.md

✅

Bluetooth Classic (BR/EDR) attacks — KNOB, BIAS, BlueBorne — and why this rig can't touch them.

bluetooth/interception.md

✅

Interception reality — advertising vs connection sniffing, pairing crypto, and what this rig can/can't do.

Theory

File

Status

What's in it

theory/relay-attacks.md

✅

The attack class that beats correct crypto — PKES/BLE/NFC relay; UWB/distance-bounding defense

theory/rolling-codes.md

✅

KeeLoq internals, RollJam/RollBack, cryptanalysis, and defenses

theory/human-layer.md

✅

The gap no patch closes — phishing, BadUSB social-eng, NFC/QR baiting; passkeys as the fix

Topics

File

Status

What's in it

topics/ai-flipper-possibilities.md

✅

What an AI agent driving the Flipper unlocks, the hardware/crypto ceiling, and injection→hardware risk.

topics/tinkering.md

✅

Maker/electronics projects, FAP/ufbt app dev, on-device JavaScript, and asset packs.

topics/security-pentest.md

✅

Honest red-team framing — capability-vs-tool matrix, methodology, ROE checklist, remediation.

topics/subghz-region-lock.md

✅

How Flipper's Sub-GHz region provisioning works, why "Missing region file" blocks TX, and the fix.

topics/use-cases.md

✅

Legitimate uses & project ideas organized by capability, with a starter-projects table.

topics/remaining-gaps.md

✅

Where capability still beats modern defenses in 2026 — deployment inertia, relay attacks, IoT floor, FM11RF08S.

Resources

File

Status

What's in it

resources/best-github-repos.md

✅

Curated GitHub repos by category, with maintenance flags

resources/community-and-video.md

✅

Discord/Reddit/forums + vetted YouTube creators

resources/flipper-ble-control.md

✅

Wireless Flipper control SOLVED — read/see/drive/launch/file-read over BLE via the flipper-ble MCP server.

resources/cool-projects.md

✅

Fun/novel projects — FlipperHTTP web apps, games, VGM DOOM, MagSpoof, Home Assistant

resources/flipper-mcp-and-ai.md

✅

Drive the Flipper from Claude — MCP servers, AgentFlipper, Mac/USB setup, AI-control risks

resources/flipper-control-playbook.md

✅

How an AI agent should drive the Flipper via the MCP toolkit — data-first algorithm, menu maps, app-entry recipes, conventions.

resources/flipper-control-mcp-server.md

✅

Gated control MCP server (Stage 3) — 14 tools (input/apps/LED/GPIO/IR+SubGHz-TX/writes + screenshot) over USB, each approved.

resources/flipper-healthwatch.md

✅

Gated, default-off launchd job that polls the Flipper read-only 3×/day (battery/storage/clock/firmware) and notifies on anomalies.

resources/flipper-read-mcp-server.md

✅

The read-only MCP server we built for this rig — 14 native mcp__flipper__* device-read tools over USB, one allowlist.

resources/github-landscape.md

✅

Leaderboard + people — top repos by stars, devs/orgs to follow, the ESP32 scene

resources/apps-badusb-automotive-misc.md

✅

Runbook for the BadUSB/HID, CAN/automotive, physical-access, crypto and misc security FAPs on my Momentum rig.

resources/apps-rfid-ibutton-infrared.md

✅

Per-app runbook for the LF RFID (125 kHz), iButton/1-Wire, and Infrared apps on the owner's maxed Momentum rig.

resources/apps-nfc.md

✅

Per-app reference for every 13.56 MHz NFC .fap on my Momentum rig — what it does, options, gotchas, sources.

resources/learning-and-docs.md

✅

Docs, cheat-sheets, and deep RF+NFC learning material by level

resources/notable-apps-and-data.md

✅

Deeper cut — pyFlipper scripting, sensor/utility apps, data/dumps, asset packs, 3D

resources/mcp-setup-claude-code.md

✅

Install busse MCP, add to Claude Code over USB, scope it read-only with gating — first safe AI↔device milestone.

resources/apps-subghz.md

✅

Per-app reference for the Sub-GHz/RF .faps on this Momentum rig — what each does, key options, use-cases, gotchas, sources.

resources/subghz-device-repos.md

✅

Device-specific Sub-GHz repos and .sub collections (TouchTunes, gates, Tesla, sensors)

resources/tools-and-software.md

✅

qFlipper, Flipper Lab, flashers, and an SD-backup checklist

resources/apps-esp-ble-nrf24.md

✅

Per-app runbook for the ESP32 / BLE / NRF24 companion FAPs on my Momentum rig — what each does, settings, hardware, sources.

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pogorelov-labs/flipper-ble-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server