pm3-mcp-server

Windows-first Model Context Protocol server that wraps the Proxmark3 Iceman/RRG CLI for MIFARE Classic workflows.

Not a raw 1:1 CLI passthrough: the core path is magic-safe write — detect card generation → route the right write command → verify → fallback on silent failure.

Authorized use only. Use on cards and systems you own or have explicit permission to test. Magic-card writes and UID changes have irreversible failure modes (e.g. Gen3 freeze).

Requirements

• Windows + Proxmark3 Iceman client (proxmark3.exe) already installed and flashed
• Python 3.10+
• Serial access to the device (do not run the official Proxmark GUI on the same COM port at the same time)

Configuration

Variable	Meaning
PM3_EXE_PATH	Absolute path to proxmark3.exe (required)
PM3_CWD	Working directory for dictionaries / relative paths (defaults to exe parent)
PM3_PORT	Serial port (default COM3)
PM3_TIMEOUT_SEC	Command timeout (default 30, hard cap 120)
PM3_KEYS_FILE	Optional path to keys.local.json

Copy keys.local.json.example → keys.local.json for site keys (gitignored). The server only reports key counts to the LLM, never the key list.

Vendor bundle folder tags (e.g. V9.0.6.7) are labels only. Real client version comes from pm3_info / proxmark3.exe --version (e.g. Iceman v4.20142). This server does not flash firmware.

Setup

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

Smoke-check the client (no card required):

& $env:PM3_EXE_PATH --version

Run

$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 snippet

{
  "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"
      }
    }
  }
}

Prefer the venv interpreter if you installed deps there:

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

Tool surface

Primary (use these first)

Tool	Role
pm3_info	hf mf info (+ fallback hf 14a info); UID/ATQA/SAK/card_type + client version
pm3_dump	Sector dump + key summary
pm3_write_magic_safe	Auto write route + post-write magic verify
pm3_access_decode	Local trailer / FF078069 access-bits decode
pm3_get_card_knowledge	Magic taxonomy snippets for context

Advanced (only when primary is insufficient): pm3_detect_magic, pm3_try_keys, pm3_read_block, pm3_read_sector, pm3_write_block, pm3_set_uid.

Magic write taxonomy

Generation	Write	Verify	Never auto
Gen1a/1b	csetblk / csetuid (optional csetblk --gdm = Gen1a wakeup only)	cgetblk	gen3freeze, gdmsetcfg
Gen2 / CUID	wrbl (--force for block0)	rdbl	same
Gen3	gen3uid / gen3blk	gen3/info paths	gen3freeze; not csetblk --gdm
Gen4 GDM	gdmsetblk (then csetblk --gdm variant)	magic read	gdmsetcfg

Device-facing responses include _raw (truncated) for graceful parse fallback.

Tests

pytest -q

Covers parser fixtures, access bits (FF078069), write router (Gen3 ≠ --gdm), and client validation (injection / whitelist / batch size).

Live hardware notes

• Place a card on the antenna before pm3_info / write tools.
• No card → ok: false, reason: "no_card" (no retry loop).
• Gen4 GDM: wrbl on trailers can report success while swallowing data — pm3_write_magic_safe verifies and falls back.
• Firmware flashing is out of scope.

License

MIT