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)

Related MCP server: mcp-uart

Configuration

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)

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

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