pm3-mcp-server

Windows-first Model Context Protocol сервер, оборачивающий CLI Proxmark3 Iceman/RRG для рабочих процессов с MIFARE Classic.

Это не прямой 1:1 пропуск CLI: основной путь — magic-safe запись — определение поколения карты → выбор правильной команды записи → проверка → откат при тихом сбое.

Только авторизованное использование. Используйте только на картах и системах, которыми вы владеете или на тестирование которых имеете явное разрешение. Запись на magic-карты и изменение UID имеют необратимые режимы отказа (например, заморозка Gen3).

Требования

• Windows + клиент Proxmark3 Iceman (proxmark3.exe) уже установлен и прошит

• Python 3.10+

• Последовательный доступ к устройству (не запускайте официальный GUI Proxmark на том же 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

Покрывают фикстуры парсера, access bits (FF078069), маршрутизатор записи (Gen3 ≠ --gdm) и проверку клиента (инъекции / белый список / размер пакета).

Примечания по реальному оборудованию

• Поместите карту на антенну перед pm3_info / инструментами записи.

• Нет карты → ok: false, reason: "no_card" (без цикла повторов).

• Gen4 GDM: wrbl на трейлерах может сообщать об успехе, проглатывая данные — pm3_write_magic_safe проверяет и откатывается.

• Прошивка прошивки вне области действия.

Лицензия

MIT