ReconGrunt/FlipperTalk
GitHub: ReconGrunt/FlipperTalk
FlipperTalk 是一个 MCP 服务器，让 AI 通过 USB 直接控制 Flipper Zero，支持存储管理、应用部署、屏幕截图、按键自动化和 JavaScript 执行等全部设备能力。
Stars: 0 | Forks: 0
# FlipperTalk
通过 Claude Code —— 或者任何 [MCP](https://modelcontextprotocol.io) 客户端，与你的 **Flipper Zero** 对话。
支持存储、应用部署、屏幕截图、按键自动化、**在设备上执行 JavaScript**，以及关于附近环境的如实反馈。
这赋予了你的 AI 实例完整的 Flipper 能力，可能性是无限的。
**以 Momentum 优先**，支持 Unleashed、RogueMaster 和官方固件。
只有一个第三方依赖。无需网络访问。破坏性操作默认隐藏。
```
"Deploy my app and show me the settings screen."
-> flipper_deploy_fap (upload, md5-verify, launch)
-> flipper_input_sequence ["DOWN","DOWN","OK"] screenshot: true
-> [the actual device screen comes back as an image]
```
## 为什么会有这个项目
qFlipper 是官方桌面应用程序，自 **2023 年 11 月** 以来就没有发布过新功能（它最后一次提交是在 2024 年 6 月，内容仅为 *“修复 Windows 构建”*）。
固件在 2025 年 12 月达到了 **1.4.3** 版本。在这段空白期内，它增加了 JavaScript 引擎、动态应用加载、重写的 NFC 协议栈、自动更新以及更为丰富的 CLI。而 qFlipper 没有暴露其中任何一项，并且无论如何都没有可供连接的 IPC、socket 或守护进程。
FlipperTalk 转而直接针对 **固件** 进行通信，支持设备通过 USB 串口实际提供的两种协议：
1. **文本 CLI** —— 交互式的 `>: ` shell
2. **protobuf RPC** —— 屏幕截图、二进制安全传输、模拟输入
只有在进行 DFU/bootloader 恢复时才会调用 `qFlipper-cli`，这是它目前唯一不可替代的功能。
## 自定义固件是一等支持目标
这些分支固件不仅仅是皮肤修改——每个分支都维护着自己的 protobuf，并且与官方固件（其 `Main.content` 的 tag 上限为 75）存在差异：
| 固件 | protobuf 差异 | FlipperTalk 的处理方式 |
|---|---|---|
| **Momentum** | `gui_send_ascii_event_request` @100；`ScreenFrame` 增加了 `bg_color`/`fg_color` | `flipper_type_text` 直接输入字符串；屏幕截图使用你实际的主题颜色 |
| **RogueMaster** | 与 Momentum 相同（它跟随的是 *Momentum 的* protobuf，而不是 Unleashed 的） | 同 Momentum |
| **Unleashed** | `PB_Network`（TCP/HTTP/WebSocket）和 `PB_Gps`，tag 76–90 | 感应功能中的 GPS 定位；网络工具存在但**默认关闭** |
所有三种方言都被合并到一个 schema 中——它们的 tag 范围不会冲突——因此无论连接的是什么，解码都是正确的。接着，固件检测会决定提供哪些*工具*，所以你永远不会看到你的设备无法支持的工具。
Momentum 的 JavaScript 引擎在实质上也更庞大，在官方模块集的基础上增加了 `subghz`、`blebeacon`、`i2c`、`spi`、`usbdisk`、`widget` 和 `vgm`。
## 安装说明
需要 Python 3.10+ 以及一台通过支持数据传输的 USB 线连接的 Flipper Zero。
```
git clone https://github.com/ReconGrunt/FlipperTalk
cd FlipperTalk
python -m venv .venv
.venv/Scripts/activate # Windows
# source .venv/bin/activate # macOS / Linux
pip install --require-hashes -r requirements.lock
pip install -e . --no-deps
```
`--require-hashes` 会通过 SHA-256 锁定每个组件。请参阅 [SECURITY.md](SECURITY.md)。
```
python -m flippertalk_mcp --list-tools # see what your config exposes
```
### Claude Code
```
claude mcp add flippertalk --scope user -- /absolute/path/to/.venv/bin/python -m flippertalk_mcp
```
### Claude Desktop / 任何 `mcpServers` 客户端
```
{
"mcpServers": {
"flippertalk": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["-m", "flippertalk_mcp"]
}
}
}
```
在 Windows 上，请使用 `C:\path\to\.venv\Scripts\python.exe`。
## 在设备上运行 JavaScript
这是此处最灵活的功能。固件 1.0+ 内嵌了 mJS，而且关键在于，当以这种方式启动脚本时，*“所有来自 `print()` 的输出都会发送到 CLI，而不是设备屏幕上”*。因此，Claude 可以编写代码、运行它并读取结果。
```
flipper_run_js { source: 'print("battery: " + require("flipper").getBatteryCharge());' }
```
脚本可以访问 GPIO、UART、通知、BadUSB、GUI 和存储——还有 Momentum 的额外模块。请先调用 `flipper_js_probe`；它会报告在当前连接的固件上实际可解析的模块，而不是盲目猜测。
## “附近有什么？”——以及这句话的真实含义
`flipper_scan_nearby` 会扫描硬件真正支持的每一个信号源，并返回结构化的结果以及一段通俗易懂的摘要。
**它不会弄虚作假。** 无法运行的信号源会被报告为 *未检查，并附带原因*——绝不会报告为“未发现任何内容”：
| 信号源 | 现实情况 |
|---|---|
| Sub-GHz | 真正的空中信号；Momentum/Unleashed 拓宽了可调范围 |
| NFC / RFID / iButton | **接触范围**——卡片必须贴在读取器上 |
| i2c / 1-Wire | 通过线缆连接到 GPIO 接口 |
| GPS | 仅限 Unleashed |
| **BLE** | **没有任何固件可以扫描它。** 原厂 `bt` 命令是 `hci info`；Momentum 的 `blebeacon` 只负责发送。需要扫描器应用或 ESP32 开发板 |
| **WiFi** | **设备上没有对应的射频模块。** 需要 ESP32 开发板 |
摘要陈述的是观察结果，而不是结论——比如 *“在 433.92 MHz 处有强信号”*，而不是 *“有人在追踪你”*。运行 `flipper_sense_capabilities` 以查看你特定设备的限制。
## 工具
默认有分为七个组的 66 个工具。`flipper_cli` 依然是通向任何固件命令的逃生舱。
**core** · 设备、信息、存储、上传/下载、应用启动与部署、截图、录屏、输入、打字、虚拟显示屏、资源包、时钟
**js** · 运行/保存/列出脚本、模块探测
**sense** · 扫描附近环境、感应设备能力、应用报告
**radio** · subghz、nfc、rfid、ibutton、infrared
**hw** · gpio、i2c、1-Wire、led、vibro、buzzer、notify、BadUSB *（受限）*
**dev** · 能力、诊断、日志、Momentum 设置
**firmware** · qFlipper-cli 状态/备份、原生 SD 更新，以及受限的 擦除/写入/抹除/恢复
**network** · Unleashed HTTP、TCP 连接/发送/关闭、GPS —— **除非明确启用，否则关闭**
设备路径是绝对路径，以 `/ext`（SD 卡）或 `/int`（内部存储）开头。
### 精简工具表面
66 个工具会在每次会话中消耗上下文。各个工具组是可以选择性开启的：
```
FLIPPERTALK_TOOLSETS=core,js,dev # 46 tools — app development
FLIPPERTALK_TOOLSETS=core # 38 tools — essentials only
FLIPPERTALK_TOOLSETS=all # everything, including network
```
精简工具不会丢失任何功能——`flipper_cli` 依然可以触达每一个固件命令。
## 对于应用开发者
`flipper_deploy_fap` 是核心循环：上传新构建的 `.fap`，通过 md5 校验，并启动它。
```
ufbt
-> flipper_deploy_fap { local_path: "dist/myapp.fap" }
-> flipper_screen_record { frames: 8, keys: ["DOWN","OK"] }
```
由于截图返回的是真实的 framebuffer，模型可以直接*查看* UI 更改的渲染结果，而不是从源码中推断。`flipper_screen_record` 将此扩展到了动画和过渡效果。
## 安全性
破坏性操作是**被隐藏的，而不仅仅是被拒绝**——它们被完全从 `tools/list` 中省略，因此从未见过它们的模型也就无法调用它们。
| 变量 | 默认值 | 作用 |
|---|---|---|
| `FLIPPERTALK_TOOLSETS` | 除 `network` 外的所有 | 暴露哪些工具组 |
| `FLIPPERTALK_ALLOW_DESTRUCTIVE` | 关闭 | 固件刷写、擦除、抹除、恢复、递归删除、DFU 重启 |
| `FLIPPERTALK_READ_ONLY` | 关闭 | 保留所有会进行修改的工具 |
| `FLIPPERTALK_LOCAL_ROOTS` | 未设置 | 将宿主机文件访问限制在允许列表内 |
| `FLIPPERTALK_DIALECT` | 自动 | 如果检测错误，强制指定固件家族 |
| `FLIPPERTALK_WRITE_CHUNK` | `512` | 每次存储写入块的字节数（64–4096） |
| `FLIPPERTALK_IDLE_TIMEOUT` | `120` | 释放空闲连接前的秒数 |
| `QFLIPPER_CLI` | 自动 | `qFlipper-cli` 的明确路径 |
来自 v0.1 的 `QFLIPPER_MCP_*` 名称在一个版本内仍然有效。
将此服务器授予模型等同于交出设备的控制权。如果你只需要进行检查，请使用 `FLIPPERTALK_READ_ONLY=1`。
## 开发
```
PYTHONPATH=src python -m unittest discover -s tests -v
```
包含 278 个测试，无需硬件。它们涵盖了针对手动计算出的黄金字节向量进行测试的 protobuf 编解码器（包括 Unleashed 的 GPS 坐标所需的 zigzag `sint32`，如果处理不当它会悄无声息地解码错误），将解码后的 PNG 输出进行逐像素比较，通过 stdio 作为子进程对服务器进行的完整 MCP 握手，针对模拟设备使用真实通信协议进行的 RPC 层测试，分支检测（包括确保 RogueMaster *不能* 被错误地检测为 Unleashed），以及未运行的信号源绝不能被报告为空的感应规则。
`proto/{official,momentum,unleashed}/` 是从各个分支自己的代码库中引入的，作为 `pb.py` 中字段编号的参考。它们永远不会被编译或执行。
## 兼容性
官方 1.x、Momentum、Unleashed 和 RogueMaster。解码时会跳过未知字段，因此增加了新消息的固件依然可以正常解析。屏幕截图假定使用标准的 128x64 显示屏。
## 许可证
MIT —— 详见 [LICENSE](LICENSE)。
独立于 Flipper Devices Inc.。这是一个使用已公开通信协议的净室实现；它既没有链接也没有派生自 qFlipper 的源代码。
标签：Flipper Zero, MCP, SOC Prime, 开发工具, 物联网, 硬件控制, 网络调试, 自动化, 逆向工具