pm3-mcp-server

一个以 Windows 为先的 Model Context Protocol 服务器，封装了 Proxmark3 Iceman/RRG CLI，用于 MIFARE Classic 工作流。

并非原始的 1:1 CLI 透传：核心路径是魔法安全写入 — 检测卡片代次 → 路由到正确的写入命令 → 验证 → 静默失败时回退。

仅限授权使用。 仅可对您拥有或已获明确测试许可的卡片和系统使用。魔法卡写入和 UID 更改具有不可逆的故障模式（例如 Gen3 冻结）。

要求

• 已安装并刷写好的 Windows + Proxmark3 Iceman 客户端（proxmark3.exe）

• Python 3.10+

• 可访问设备的串口（请勿在同一 COM 口上同时运行官方 Proxmark GUI）

Related MCP server: mcp-uart

配置

复制 keys.local.json.example → keys.local.json 以配置站点密钥（已被 gitignore 忽略）。服务器仅向 LLM 报告密钥数量，绝不会报告密钥列表。

供应商捆绑包文件夹标签（例如 V9.0.6.7）仅为标签。实际客户端版本来自 pm3_info / proxmark3.exe --version（例如 Iceman v4.20142）。此服务器不刷写固件。

设置

git clone https://github.com/wocessade/pm3-mcp-server.git
cd pm3-mcp-server
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pytest -q

对客户端进行冒烟检查（无需卡片）：

& $env:PM3_EXE_PATH --version

运行

$env:PM3_EXE_PATH = "C:\path\to\proxmark3.exe"
$env:PM3_CWD = "C:\path\to\proxmark3"
$env:PM3_PORT = "COM3"
python server.py

Cursor / Claude MCP 代码片段

{
  "mcpServers": {
    "pm3": {
      "command": "python",
      "args": ["C:\\path\\to\\pm3-mcp-server\\server.py"],
      "env": {
        "PM3_EXE_PATH": "C:\\path\\to\\proxmark3.exe",
        "PM3_CWD": "C:\\path\\to\\proxmark3",
        "PM3_PORT": "COM3"
      }
    }
  }
}

如果您在 venv 中安装了依赖项，请优先使用 venv 解释器：

"command": "C:\\path\\to\\pm3-mcp-server\\.venv\\Scripts\\python.exe"

工具接口

主要（优先使用这些）

高级（仅在主要工具不足时使用）：pm3_detect_magic、pm3_try_keys、pm3_read_block、pm3_read_sector、pm3_write_block、pm3_set_uid。

魔法写入分类

面向设备的响应包含 _raw（截断），以便优雅地解析回退。

测试

pytest -q

涵盖解析器夹具、访问位（FF078069）、写入路由器（Gen3 ≠ --gdm）和客户端验证（注入/白名单/批大小）。

真实硬件说明

• 在 pm3_info / 写入工具之前，请将卡片放在天线上。

• 无卡片 → ok: false、reason: "no_card"（无重试循环）。

• Gen4 GDM：对 trailer 执行 wrbl 可能会在吞掉数据的同时报告成功 — pm3_write_magic_safe 会进行验证并回退。

• 固件刷写不在范围内。

许可证

MIT