roostercoopllc/flipper-mcpAI 驱动的 Flipper Zero MCP 服务器。通过 WiFi 使用 Claude 或任何 MCP 客户端控制 SubGHz、NFC、RFID、IR、BLE、GPIO 等。
一个 Rust MCP（模型上下文协议）服务器，直接运行在 Flipper Zero 的 WiFi Dev Board v1（ESP32-S2）上，使 AI 代理能够通过网络控制 Flipper Zero。
这个项目将 MCP 服务器放在 Flipper 本身上。任何兼容 MCP 的 AI 客户端（Claude Desktop、Claude Code 等）都可以连接，并将 Flipper 的功能作为工具使用——SubGHz、NFC、RFID、IR、GPIO、BadUSB、iButton、文件存储等。
与其他需要 USB 连接主机的项目不同，flipper-mcp 运行在连接到 Flipper 的 ESP32-S2 WiFi 模块上。Flipper 成为一个独立的、可通过网络访问的工具。
本地（同一网络）：
MCP 客户端 ──HTTP──► flipper-mcp.local:8080 (ESP32-S2) ──UART──► Flipper Zero
远程（跨网络）：
MCP 客户端 ──HTTP──► 中继服务器 ◄──WebSocket── ESP32-S2 ──UART──► Flipper Zero
ESP32-S2 运行一个实现 MCP 协议的 HTTP 服务器。它通过 UART 以 115200 波特率将 MCP 工具调用转换为 Flipper Zero CLI 命令。配套的中继服务器支持从任何网络进行远程访问。
flipper-mcp.local我应该连接到哪个设备？
| 阶段 | 连接到 | 备注 |
|---|---|---|
| 刷写固件 | WiFi Dev Board USB-C | 开发板有自己的 USB 端口，与 Flipper 分开 |
| 串口监控 | WiFi Dev Board USB-C | 与刷写相同的 USB 连接 |
| SD 卡配置文件 | Flipper Zero SD 卡 | 将 SD 卡插入 Flipper，或取出并挂载到 PC |
| 服务器控制命令 | Flipper Zero SD 卡 | 在 apps_data/flipper_mcp/ 中创建 server.cmd 文件 |
| UART 通信 | 自动 | WiFi Dev Board 和 Flipper 通过 GPIO 排针连接 |
| MCP HTTP 请求 | WiFi Dev Board IP:8080 | 通过你的 WiFi 网络连接 |
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install espup
espup install
source ~/export-esp.sh # 在每个新终端中运行此命令
cargo install espflash
cargo install ldproxy
sudo apt install -y git curl gcc build-essential pkg-config libudev-dev libssl-dev python3 python3-venv cmake ninja-build
完整设置说明见 docs/SETUP.md
source ~/export-esp.sh
cd firmware
cargo build --release --target xtensa-esp32s2-espidf
espflash flash --monitor target/xtensa-esp32s2-espidf/release/flipper-mcp
在 Flipper SD 卡的 SD:/apps_data/flipper_mcp/config.txt 路径下创建 config.txt：
wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp
或者直接从 Flipper 配置，使用配套 FAP（见步骤 5）：
Apps → Tools → Flipper MCP → Configure WiFi
首次启动时如果没有配置文件，ESP32 会等待并将 status=needs_config 写入状态文件。Flipper FAP 将在状态屏幕上显示此信息。
在配置 AI 客户端之前，使用 curl 确认服务器可访问：
# 快速健康检查
curl http://flipper-mcp.local:8080/health
# 完整验证——初始化 + 列出所有可用工具
./scripts/test-connection.sh
# 如果你的操作系统无法解析 mDNS，直接传入 IP：
./scripts/test-connection.sh 192.168.x.xxx
从 Flipper MCP → Status 菜单获取 Flipper 的 IP，然后测试：
BLE 信标广播（发送伪造的 BLE 广播）：
curl -X POST http://192.168.0.58:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ble_beacon","arguments":{"data":"020106"}}}'
BLE HID 键盘（模拟无线键盘并输入）：
# 启动 HID 模拟
curl -X POST http://192.168.0.58:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ble_hid_start","arguments":{}}}'
# 输入消息
curl -X POST http://192.168.0.58:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ble_hid_type","arguments":{"text":"Hello from Flipper!"}}}'
# 停止 HID 模拟
curl -X POST http://192.168.0.58:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ble_hid_stop","arguments":{}}}'
IR 发送（发送红外遥控代码）：
# NEC 协议 IR 代码（通用电视电源按钮）
curl -X POST http://192.168.0.58:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ir_tx","arguments":{"protocol":"NEC","address":"00","command":"01","repeat":0}}}'
SubGHz 接收（监听 433.92 MHz 上的无线信号）：
curl -X POST http://192.168.0.58:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"subghz_rx","arguments":{"frequency":433920000,"duration":5000}}}'
将 192.168.0.58 替换为你 Flipper 的实际 IP 地址。
然后添加到你的 Claude Desktop 配置（claude_desktop_config.json）：
{
"mcpServers": {
"flipper": {
"url": "http://flipper-mcp.local:8080/mcp"
}
}
}
将 flipper-app/ 中的配套 Flipper MCP 应用安装到 Flipper Zero。使用 ufbt 构建，并将 .fap 复制到 SD:/apps/Tools/：
cd flipper-app && ufbt # 生成 flipper_mcp.fap
# 将 flipper_mcp.fap 复制到 Flipper SD 卡的 apps/Tools/ 下
该应用出现在 Apps → Tools → Flipper MCP 中，并提供：
| 屏幕 | 功能 |
|---|---|
| Status | 从 ESP32 请求最新状态更新，显示 IP、SSID、服务器状态、版本 |
| Start / Stop / Restart | 控制 MCP HTTP 服务器生命周期 |
| Reboot Board | 重启 ESP32 WiFi Dev Board |
| Configure WiFi | 屏幕键盘输入 SSID + 密码；将 config.txt 写入 SD 卡 |
| View Logs | ESP32 每 30 秒写入的可滚动诊断日志 |
| Tools List | ESP32 上当前注册的所有 MCP 工具的可滚动列表 |
| Refresh Modules | 触发 ESP32 上的 FAP 发现重新扫描 + modules.toml 重新加载 |
该应用通过 SD 卡文件通信（除 GPIO 排针外无需额外接线）。Configure WiFi 是首次启动向导——无需手机、浏览器或 PC 脚本。
自托管（在任何地方运行二进制文件）：
./scripts/build-relay.sh
./target/release/flipper-mcp-relay --listen 0.0.0.0:9090
# 然后在 Flipper SD 卡的 config.txt 中添加 relay_url：
# relay_url=ws://your-server:9090/tunnel
云部署（AWS 或 GCP，带 TLS + DNS）：
# 引导状态存储，然后部署
./infra/bootstrap/aws.sh # 或 ./infra/bootstrap/gcp.sh
cd infra/aws && cp terraform.tfvars.example terraform.tfvars
tofu init && tofu apply
# 输出中继 URL 和可直接粘贴的 wifi-config.sh 命令
完整说明见 RELAY.md。
| 类别 | 工具 | 描述 |
|---|---|---|
| SubGHz | subghz_tx, subghz_rx, subghz_decode_raw, subghz_chat, subghz_tx_from_file | 射频操作 |
| NFC | nfc_detect, nfc_read, nfc_emulate, nfc_field | NFC 标签交互 |
| RFID | rfid_read, rfid_emulate, rfid_write | 低频 RFID |
| 红外 | ir_tx, ir_rx | 红外遥控 |
| GPIO | gpio_read, gpio_write, gpio_set_mode | 引脚 I/O 控制 |
| BadUSB | badusb_run, badusb_list | USB HID 攻击 |
| iButton | ibutton_read, ibutton_emulate | 1-Wire 钥匙扣 |
| 存储 | storage_list, storage_read, storage_write, storage_remove, storage_stat | SD 卡文件管理 |
| 系统 | system_device_info, system_power_info, system_power_reboot, system_ps, system_free, system_uptime | 设备管理 |
| BLE | ble_info, ble_beacon, ble_beacon_stop, ble_hid_start, ble_hid_type, ble_hid_press, ble_hid_mouse, ble_hid_stop | 低功耗蓝牙（信标广播 + HID 模拟） |
| 应用 | app_launch_{name}（从 SD 卡自动发现） | 应用管理 |
可以通过 TOML 配置文件或在 SD 卡上安装 FAP 应用来添加自定义工具。每个工具的复制粘贴 curl 命令见 OPERATIONS.md。
你不需要 Claude 订阅即可使用 flipper-mcp。Open WebUI 是一个免费、自托管的 ChatGPT 风格界面，原生支持 MCP Streamable HTTP（v0.6.31+）。将其与 Ollama 搭配使用，可实现完全本地、离线的 AI 驱动 Flipper 控制。
# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh
# 拉取支持工具调用的模型
ollama pull llama3.1 # 8B — 速度与能力良好平衡
# 或：ollama pull qwen2.5 # 强大的工具调用能力，擅长结构化输出
# 或：ollama pull mistral # 轻量、快速的工具使用