Skip to main content
Glama
@woyax/mcp-chestnyi-znak

@woyax/mcp-chestnyi-znak

by woyaxnini

@woyax/mcp-chestnyi-znak

License: MIT + Commons Clause

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.


Related MCP server: Legion Database MCP Server

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.

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.

Available Tools

10 tools
chz_balance_allGet Balance for All Product GroupsA

Get marking code balance across all product groups for the current participant. Endpoint: GET /api/v3/true-api/elk/product-groups/balance/all

Inputs: no named parameters.

chz_cis_infoGet Public CIS InfoA

Get public information about marking codes by list of CIS values. Returns status, owner, product details for each code. Endpoint: POST /api/v3/true-api/cises/info

Inputs: pg (required), cises (required).

chz_doc_cis_listGet Marking Codes in DocumentB

Get list of marking codes (CIS) included in a document. Endpoint: GET /api/v4/true-api/doc/{id}/cises

Inputs: pg (required), docId (required).

chz_doc_infoGet Document InfoC

Get detailed information about a specific document by its ID. Endpoint: GET /api/v4/true-api/doc/{id}/info

Inputs: id (required), pg (required).

chz_doc_listList DocumentsA

Get list of documents in Chestnyi Znak for a given product group. Returns document IDs, types, statuses, dates. Endpoint: GET /api/v4/true-api/doc/list

Inputs: pg (required), limit.

chz_participant_checkCheck Participant by INNA

Check if a company is a registered participant in Chestnyi Znak by their INN (tax ID). Returns registration status and details for each INN. Endpoint: GET /api/v3/true-api/participants?inns={inns}

Inputs: inns (required).

chz_product_infoGet Product Info by GTINA

Get product card information by GTIN code. Pass a JSON body with gtin or other product identifiers. Endpoint: POST /api/v4/true-api/product/info

Inputs: pg (required), body (required).

chz_receipt_listGet Receipts (Withdrawals)B

Get list of withdrawal receipts (sales/disposals of marking codes) for a product group. Endpoint: GET /api/v4/true-api/receipt/list

Inputs: pg (required).

chz_warehouse_balanceGet Virtual Warehouse BalanceB

Get virtual warehouse balance (marking codes on hand) for a product group. Pass a JSON body with filter criteria. Endpoint: POST /api/v3/true-api/warehouse/balance

Inputs: pg (required), body (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct resource or operation within the Chestnyi Znak system, such as documents, CIS codes, products, and participants. There is no overlap or ambiguity between tool purposes.

    Naming Consistency5/5

    All tools follow the consistent pattern 'chz_<resource>_<action>' using snake_case. Naming is uniform and predictable, aiding in tool selection.

    Tool Count5/5

    With 10 tools, the server covers essential query operations across multiple facets of the marking code system. The count is well-scoped for the domain.

    Completeness4/5

    The tool set covers key read operations but lacks tools for individual receipt details or document creation/modification, which are minor gaps given the apparent informational focus.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server providing tools for interacting with 1С:Напарник AI, including asking questions, syntax explanation, code review, and documentation search. Also serves as a web chat interface and OpenAI-compatible API gateway.
      110
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A unified MCP server for querying and managing multiple database types (PostgreSQL, MySQL, SQL Server, etc.) via natural language through AI assistants.
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for TeamDesk databases, enabling CRUD operations, search, and document generation via natural language.
      4
      MIT