pm3-mcp
MCP服务器，通过持续的交互会话，使AI助手（Claude Code等）可以直接访问Proxmark3 RFID/NFC研究工具。
它做什么
服务器生成一个Proxmark3客户端进程，并在工具调用期间保持其活动状态。您可以让Claude读取、写入、克隆和分析RFID/NFC卡，而无需自己编写任何pm3命令。
对话示例：
You: "Scan whatever card is on the reader"
Claude: [calls pm3_connect, then pm3_command with "auto"]
Claude: "Found an EM 410x card with ID 1D00D2A924. This is a low-frequency
125kHz proximity card commonly used for door access."
You: "Clone it to a T5577"
Claude: [calls pm3_command with "lf em 410x clone --id 1D00D2A924"]
Claude: "Done. The T5577 card now emulates your original EM 410x."先决条件
- Node.js 18+
- Proxmark3客户端 编译和工作(RRG/冰人叉子)
- 通过以下方式进行验证： pm3 --version 或 proxmark3 --version
- Proxmark3设备通过USB连接
安装
git clone https://github.com/KratosUAE/pm3_claude_mcp.git
cd pm3_claude_mcp
npm install
npm run build配置
所有配置都是通过环境变量进行的：
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
PM3_BINARY_PATH | 否 | 通过自动检测 which pm3 / which proxmark3，回退 /usr/local/bin/pm3 | pm3二进制文件的路径 |
PM3_CWD | 否 | pm3二进制文件的父目录 | pm3进程的工作目录（字典、CARDS等所在的位置） |
PM3_IDLE_TIMEOUT | 没有 | 3000 | 空闲超时（毫秒）（在最后一次输出后等待多长时间才能认为命令完成） |
PM3_MAX_TIMEOUT | 没有 | 120000 | 任何单个命令的最大超时时间（毫秒） |
PM3_DEBUG | 否 | 关闭 | 设置为 1, true，或 yes 启用stderr的调试日志记录 |
Claude代码设置
添加到MCP配置(~/.claude/mcp.json 或项目 .mcp.json):
{
"mcpServers": {
"proxmark3": {
"command": "node",
"args": ["/absolute/path/to/pm3_claude_mcp/dist/index.js"],
"env": {
"PM3_BINARY_PATH": "/path/to/your/proxmark3/pm3"
}
}
}
}重新启动Claude Code以获取新的MCP服务器。
工具参考
| 工具 | 参数 | 说明 |
|---|---|---|
pm3_connect | port? （string）--串行端口，例如。 /dev/ttyACM0 | 连接到Proxmark3。如果省略，则自动检测端口。 |
pm3_command | command （string）——任意pm3命令； timeout_ms? （number）--override max timeout | 发送命令并获取响应。 |
pm3_status | none | 检查会话状态和设备信息。 |
pm3_disconnect | none | 断开连接并关闭会话。 |
状态机
DISCONNECTED ──connect()──> CONNECTING ──success──> CONNECTED
^ | |
| error error / process exit
| | |
| v v
+────── disconnect() ── ERROR <───────────────────+
| |
+────── connect() ────────+ (auto-recovery: cleanup + reconnect)- 断开连接：没有运行pm3进程。已准备好连接。
- 连接：生成pm3进程并等待横幅。
- 已连接：准备接受命令。一次一个命令。
- 错误：出了点问题。呼叫
pm3_connect再次自动恢复。
故障排除
“找不到pm3二进制文件或无法执行”
集 PM3_BINARY_PATH 转到pm3/proxmark3二进制文件的完整路径：
export PM3_BINARY_PATH=$(which pm3)“未连接。请先调用connect（）。”
会话未处于活动状态。使用 pm3_connect 在发送命令之前。
“另一个命令正在执行中”
一次只能运行一个命令。等待当前命令完成。
命令输出为空
- 设备可能已物理断开连接。服务器将检测到此情况并移动到ERROR状态。
- 某些命令不产生输出。尝试
hw status以验证连接。
“已连接。请先断开连接。”
呼叫 pm3_disconnect 在再次连接之前，或者让错误恢复处理它。
串行端口权限被拒绝
将您的用户添加到 dialout 组（Linux）或检查USB权限：
sudo usermod -aG dialout $USER
# Log out and back in服务器崩溃后pm3进程变成僵尸
如果MCP服务器在没有清理的情况下崩溃，pm3进程可能会占用串行端口：
pkill -f "pm3\|proxmark3"局限性
- 单一设备：每个服务器实例一个Proxmark3设备。
- 无流媒体：命令完成后收集并返回输出（空闲超时检测）。没有实时流媒体。
- 串行端口独占访问：一次只能有一个进程使用串行端口。连接前关闭其他pm3实例。
- 空闲超时检测：响应结束由输出静音检测到
PM3_IDLE_TIMEOUTms。非常慢的命令可能需要自定义timeout_ms.
技术细节
- 运输：stdio（通过stdin/stdout的MCP协议）
- 会话模型：具有管道stdin/stdout的持久化子进程
- 日志记录：所有日志输出都进入stderr（stdout保留给MCP协议）
- 并发：每个会话一次一个命令，连接/断开操作时使用互斥体
许可证
麻省理工学院