# pm3-mcp-server

Windows-first [Model Context Protocol](https://modelcontextprotocol.io/) 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

```powershell
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):

```powershell
& $env:PM3_EXE_PATH --version
```

## Run

```powershell
$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

```json
{
  "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:

```json
"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

```powershell
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