@woyax/mcp-chestnyi-znak

MCP-сервер для Честного Знака — российской национальной системы маркировки товаров (True API).

Позволяет AI-ассистентам (Claude, Cursor и др.) запрашивать коды маркировки, документы, остатки на виртуальном складе и данные участников напрямую через естественный язык.

Первый в мире MCP-сервер для True API Честного Знака.

Инструменты (10 штук)

Документы и коды маркировки

| Инструмент | Описание | |------------|----------| | chz_doc_list | Список документов по товарной группе | | chz_doc_info | Детальная информация по документу по ID | | chz_doc_cis_list | Коды маркировки в составе документа | | chz_cis_search | Поиск кодов маркировки по фильтрам | | chz_cis_info | Публичная информация по списку КМ | | chz_product_info | Карточка товара по GTIN |

Остатки и справочники

| Инструмент | Описание | |------------|----------| | chz_balance_all | Баланс КМ по всем товарным группам | | chz_warehouse_balance | Остатки виртуального склада по группе | | chz_participant_check | Проверка участника по ИНН | | chz_receipt_list | Список чеков выбытия по группе |

Разработка новых инструментов продолжается.

Получение токена

Сервер требует JWT-токен из личного кабинета Честного Знака. Получение токена задействует ГОСТ-криптографию (КриптоПро + УКЭП) и выходит за рамки данного пакета.

Получение токена можно автоматизировать — с помощью локального скрипта на КриптоПро, микросервиса подписи, USB-over-IP с аппаратным токеном или облачного HSM. Также возможно получить токен вручную через веб-интерфейс Честного Знака. Подходящий способ зависит от инфраструктуры, ОС, типа сертификата и требований к безопасности. Поскольку вариантов и ограничений много и они сугубо индивидуальны, это выделяется в отдельную интеграционную задачу. Мы тоже занимаемся такими настройками — обращайтесь.

Срок жизни токена: ~8–12 часов. Обновите файл по истечении — сервер подхватит новый токен автоматически, без перезапуска.

Установка и настройка

Claude Desktop

Добавьте в claude_desktop_config.json:

Sandbox:

{
  "mcpServers": {
    "chestnyi-znak": {
      "command": "npx",
      "args": ["-y", "@woyax/mcp-chestnyi-znak"],
      "env": {
        "CHZ_TOKEN_FILE": "/path/to/your/token",
        "CHZ_ENV": "sandbox"
      }
    }
  }
}

Боевой контур:

{
  "mcpServers": {
    "chestnyi-znak": {
      "command": "npx",
      "args": ["-y", "@woyax/mcp-chestnyi-znak"],
      "env": {
        "CHZ_TOKEN_FILE": "/path/to/your/token"
      }
    }
  }
}

CHZ_ENV по умолчанию "prod" если не задан.

Важно: токен в файле и значение CHZ_ENV должны соответствовать друг другу — sandbox-токен не работает на боевом контуре и наоборот.

Переменные окружения

| Переменная | Обязательна | По умолчанию | Описание | |------------|-------------|--------------|----------| | CHZ_TOKEN_FILE | Да | — | Абсолютный путь к файлу с JWT-токеном | | CHZ_ENV | Нет | prod | Контур: sandbox или prod |

Автор и поддержка

Разработал Oleg Alekseev — архитектор ERP/AI-интеграций.

• 📧 [email protected] · [email protected]
• 💬 Telegram: @ale_oleg · Канал: @woyax_ai
• 💬 MAX: max.ru/id503610654564_biz

Нужна помощь с интеграцией AI-агентов с ERP, CRM или Честным Знаком? Кастомные MCP-серверы, n8n-воркфлоу, AI-автоматизация — пишите.

Лицензия

MIT + Commons Clause © Oleg Alekseev

Свободно для личного и корпоративного использования. Перепродажа в виде хостируемого сервиса требует разрешения автора. Подробнее — LICENSE.