pm3-mcp-server

Windows 우선 Model Context Protocol 서버로, Proxmark3 Iceman/RRG CLI를 MIFARE Classic 워크플로에 맞게 래핑합니다.

단순한 1:1 CLI 패스스루가 아닙니다. 핵심 경로는 매직 세이프 쓰기(magic-safe write) 입니다 — 카드 세대 감지 → 올바른 쓰기 명령 라우팅 → 검증 → 조용한 실패 시 폴백.

승인된 사용만 가능합니다. 소유하거나 명시적 테스트 허가를 받은 카드와 시스템에서만 사용하세요. 매직 카드 쓰기 및 UID 변경은 되돌릴 수 없는 실패 모드(예: Gen3 freeze)가 있습니다.

요구 사항

• Windows + Proxmark3 Iceman 클라이언트(proxmark3.exe)가 이미 설치 및 플래시되어 있어야 함

• Python 3.10+

• 장치에 대한 시리얼 액세스(공식 Proxmark GUI를 동일한 COM 포트에서 동시에 실행하지 마세요)

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 인터프리터를 선호하세요:

"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: 트레일러에 wrbl이 성공을 보고하면서 데이터를 삼킬 수 있음 — pm3_write_magic_safe가 검증하고 폴백합니다.

• 펌웨어 플래싱은 범위 밖입니다.

라이선스

MIT