pm3-mcp-server

WindowsファーストのModel Context Protocolサーバーで、MIFARE Classic ワークフロー向けにProxmark3 Iceman/RRG CLIをラップします。

生の1:1 CLIパススルーではありません。コアパスはマジックセーフ書き込みです — カード世代の検出 → 適切な書き込みコマンドのルーティング → 検証 → サイレント失敗時のフォールバック。

許可を得た用途のみ。 自分が所有する、または明示的にテスト許可を得たカードとシステムにのみ使用してください。マジックカードの書き込みやUID変更には、取り返しのつかない失敗モードがあります（例: Gen3フリーズ）。

要件

• Windows + Proxmark3 Icemanクライアント（proxmark3.exe）がインストール済みでフラッシュ済みであること

• Python 3.10+

• デバイスへのシリアルアクセス（同じCOMポートで公式Proxmark GUIを同時に実行しないこと）

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