内容
<div align="center">
# 🐬 剪贴板
**用自然语言驱动你的Flipper Zero。**
剪贴板是一个[MCP](https://modelcontextprotocol.io)服务器，通过USB串口将[Flipper Zero](https://flipperzero.one)暴露为原生工具，适用于Claude Code（和其他MCP客户端）- 读取GPIO，捕获和重放亚GHz，扫描NFC/RFID，模拟卡，浏览设备文件系统，恢复MIFARE Classic密钥等。无需模型API积分。
</div>
---
## ✨ 看起来像这样
连接后，你只需要*询问* - 模型会选择合适的工具：
> 💬 *"我的Flipper是否连接，并且电池电量是多少？*"
> → `flipper_state` → *已连接 — Pelima on mntm-012，电池80%.*
> 💬 *"在433.92 MHz下捕获亚GHz信号10秒，并告诉我看到了多少个数据包。*"
> → `flipper_subghz_rx` → *在10秒内捕获了3个数据包.*
> 💬 *"列出设备上的应用程序，然后打开NFC应用程序。*"
> → `flipper_loader_list` → `flipper_loader_open`
每个功能都是一个独立的、模式验证的MCP工具，因此你始终使用纯英语。
## 🚀 快速开始
> **要求：** Python 3.12+，[uv](https://docs.astral.sh/uv/)，以及连接到USB的Flipper Zero，运行**[Momentum](https://momentum-fw.dev/)固件**。
```bash
# 1. 安装（为您处理macOS uv/.pth问题）
git clone https://github.com/Realgagenichols/clipper.git
cd clipper
make sync
# 2. 向Claude Code注册
claude mcp add clipper -- /绝对路径/to/clipper/scripts/clipper-mcp-stdio.sh
```
然后启动一个Claude Code会话，并要求它使用`flipper_state`检查电池。就是这样。
要启用传输/模拟/状态更改工具，请添加安全门（参见[安全性和负责任的使用](#-安全性和负责任的使用)）：
```bash
claude mcp add clipper -- env CLIPPER_SAFETY=1 /绝对路径/to/clipper/scripts/clipper-mcp-stdio.sh
```
服务器在没有设备连接的情况下正常启动 - 只有触摸串口的工具报告断开连接，并在您重新插入时自动重新连接。
## 🧰 工具
32种工具，按子系统分组。 **⚡ = 发射** （传输RF/IR/USB）· **🔒 = 状态更改** 。除非启用[安全门](#-安全性和负责任的使用)，否则两者均被阻止。
#### 设备和诊断
| 工具 | 描述 | |
|------|-------------|:--:|
| `flipper_state` | 连接状态，名称，固件，电池 | |
| `flipper_uptime` | 设备运行时间 | |
| `flipper_datetime` | 读取设备时钟（RTC） | |
| `flipper_diagnostics` | 堆栈 + 任务诊断 | |
| `flipper_power` | 关机 / 重启 / 重启到DFU | 🔒 |
| `flipper_power_otg` | 切换外部5V OTG输出 | 🔒 |
#### GPIO
| 工具 | 描述 | |
|------|-------------|:--:|
| `flipper_gpio_read` | 读取GPIO引脚级别 | |
| `flipper_gpio_write` | 写入GPIO引脚级别 | |
#### 红外
| 工具 | 描述 | |
|------|-------------|:--:|
| `flipper_ir_rx` | 接收IR信号（基于超时） | |
| `flipper_ir_tx` | 传输IR信号 | ⚡ |
#### 亚GHz
| 工具 | 描述 | |
|------|-------------|:--:|
| `flipper_subghz_rx` | 捕获亚GHz数据包（基于超时） | |
| `flipper_subghz_tx` | 传输亚GHz信号 | ⚡ |
| `flipper_subghz_tx_from_file` | 重放保存的`.sub`文件 | ⚡ |
#### NFC · RFID · iButton
| 工具 | 描述 | |
|------|-------------|:--:|
| `flipper_nfc_read` | 读取NFC标签 | |
| `flipper_rfid_read` | 读取125 kHz RFID卡 | |
| `flipper_rfid_emulate` | 模拟125 kHz RFID卡（基于超时） | ⚡ |
| `flipper_ibutton_emulate` | 模拟iButton密钥（基于超时） | ⚡ |
| `flipper_mfkey_crack` | 恢复MIFARE Classic密钥（mfkey32v2） | 🔒 |
#### USB / HID
| 工具 | 描述 | |
|------|-------------|:--:|
| `flipper_badusb_run` | 运行DuckyScript有效载荷 | ⚡ |
#### 存储
| 工具 | 描述 | |
|------|-------------|:--:|
| `flipper_storage_info` | 文件系统空间信息 | |
| `flipper_storage_list` | 列出目录 | |
| `flipper_storage_stat` | 状态路径 | |
| `flipper_storage_md5sum` | 设备上文件的MD5哈希 | |
| `flipper_storage_read` | 读取文件（可选下载到主机） | |
| `flipper_storage_write` | 将文件写入设备 | 🔒 |
#### 应用程序和设备反馈
| 工具 | 描述 | |
|------|-------------|:--:|
| `flipper_loader_open` | 在设备上打开应用程序 | |
| `flipper_loader_list` | 列出可用应用程序 | |
| `flipper_loader_info` | 报告正在运行的应用程序 | |
| `flipper_loader_close` | 关闭正在运行的应用程序 | |
| `flipper_led_set` | 设置设备LED状态 | |
| `flipper_led_color` | 设置设备LED颜色 | |
| `flipper_vibro_set` | 切换振动电机 | |
## 🔐 安全性和负责任的使用
**默认情况下**，传输（IR/亚GHz TX，文件重放，BadUSB），模拟凭证（RFID/iButton）或更改设备状态（存储写入，密钥恢复，关机/重启，5V OTG）的工具被**阻止**。使用以下命令解锁：
```bash
CLIPPER_SAFETY=1
```
- **审计跟踪。** 每次受控调用 - 允许或拒绝 - 都会追加到`~/.clipper/audit.log`（覆盖`CLIPPER_AUDIT_PATH`）。它记录操作，传输，结果和参数，**从不**记录机密数据（诸如RFID/iButton密钥之类的凭证数据被编辑）。
- **频率允许列表。** 亚GHz **传输** 受到允许列表的限制（覆盖`CLIPPER_SGHZ_ALLOWED_MHZ`）。接收不受限制。
- **依法使用。** 剪贴板可以传输RF并模拟访问凭证。仅在您拥有或明确授权测试的硬件，信号和凭证上使用它。您有责任遵守当地的无线电和计算机滥用法。
## ⚙️ 配置
所有配置均通过环境变量进行：
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `CLIPPER_SAFETY` | 未设置 | 设置为`1`以解锁发射/状态更改工具 |
| `CLIPPER_FLIPPER_PORT` | 自动检测 | 要使用的串行端口（例如`/dev/cu.usbmodemflip_Xxxx`） |
| `CLIPPER_SGHZ_ALLOWED_MHZ` | 内置列表 | 以逗号分隔的允许亚GHz TX频率（MHz）列表 |
| `CLIPPER_DOWNLOAD_DIR` | `~/.clipper/flipper-files` | `flipper_storage_read`下载的位置 |
| `CLIPPER_AUDIT_PATH` | `~/.clipper/audit.log` | 审计日志位置 |
| `CLIPPER_LOG_LEVEL` | `INFO` | 日志级别（日志输出到stderr；stdout是JSON-RPC流） |
> `CLIPPER_ALLOW_EMIT=1`作为`CLIPPER_SAFETY=1`的废弃别名被认可。
## 🛠️ 工作原理
```
Claude / MCP客户端 ──stdio（JSON-RPC）──▶ 剪贴板MCP服务器
│
操作注册表 ── 每个操作 = 一个MCP工具
│
FlipperConnection（单个锁定串口）
│ │
文本CLI命令 二进制RPC（protobuf）
▼
Flipper Zero
```
单个`FlipperConnection`拥有异步锁后面的串口，因此并发工具调用被干净地序列化。 大多数工具分发到Flipper的文本CLI；二进制安全的 文件传输使用RPC protobuf协议。 连接在操作之间将线路排空至静止状态，并在设备重启/重新枚举时自动恢复。
## 🧑💻 开发
```bash
make test # 运行完整的测试套件
make lint # ruff
# 单个测试文件
UV_NO_EDITABLE=0 uv run pytest tests/test_mcp.py -v
```
欢迎贡献 - 请保持工具小巧且模式验证，增加新行为的测试（TDD），并在打开PR之前运行`make test && make lint`。
## 🙏 致谢
- [Flipper Zero](https://flipperzero.one)团队和[Momentum固件](https://momentum-fw.dev/)项目。
- [模型上下文协议](https://modelcontextprotocol.io)。
- MIFARE Classic密钥恢复端口将Crypto1 / mfkey32v2算法从Flipper固件和proxmark3血统中移植。
## 📄 许可证
[MIT](LICENSE) © Gage Nichols
