Chestnyi Znak MCP Server

@woyax/mcp-chestnyi-znak

MCP server for Chestnyi Znak (Честный Знак) — Russia's national product labelling system (True API).

Enables AI assistants (Claude, Cursor, etc.) to query marking codes, documents, warehouse balances, and participant data directly via natural language.

First MCP server for Chestnyi Znak True API.

---

Tools (10 total)

Documents & Marking Codes

Tool	Description
chz_doc_list	List documents for a product group
chz_doc_info	Get details of a specific document by ID
chz_doc_cis_list	List marking codes included in a document
chz_cis_search	Search marking codes by filter criteria
chz_cis_info	Get public info for a list of CIS codes
chz_product_info	Get product card by GTIN

Balance & Reference

Tool	Description
chz_balance_all	Balance of marking codes across all product groups
chz_warehouse_balance	Virtual warehouse balance for a product group
chz_participant_check	Check company registration status by INN
chz_receipt_list	List withdrawal receipts for a product group

Development of new tools is ongoing.

---

Getting a Token

This server requires a JWT token from your Chestnyi Znak personal account. Token acquisition involves GOST cryptography (КриптоПро + УКЭП) and is outside the scope of this package.

Token retrieval can be automated — using a local КриптоПро script, a signing microservice, USB-over-IP with a hardware token, or a cloud HSM. It can also be done manually via the Chestnyi Znak web interface. The right approach depends on your infrastructure, OS, certificate type, and security requirements. Because the options and constraints vary significantly from case to case, this is treated as a separate integration task. We handle this kind of setup as well — feel free to reach out.

Token lifetime: ~8–12 hours. Update the file when it expires — the server picks it up automatically without restart.

---

Installation & Configuration

Claude Desktop

Add to your 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"
      }
    }
  }
}

Production:

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

CHZ_ENV defaults to "prod" if not set.

Important: the token file and the CHZ_ENV value must match — a sandbox token won't work on the production endpoint and vice versa.

---

Environment Variables

Variable	Required	Default	Description
CHZ_TOKEN_FILE	Yes	—	Absolute path to file containing the JWT token
CHZ_ENV	No	prod	Contour: sandbox or prod

---

Author & Support

Built by Oleg Alekseev — ERP/AI integration architect.

• 📧 [email protected] · [email protected]
• 💬 Telegram: @ale_oleg · Channel: @woyax_ai
• 💬 MAX: max.ru/id503610654564_biz

Need help integrating AI agents with your ERP, CRM, or Chestnyi Znak? Custom MCP servers, n8n workflows, AI automation — contact me.

---

License

MIT + Commons Clause © Oleg Alekseev

Free to use for personal and corporate purposes. Selling as a hosted service requires author's permission. See LICENSE for details.