didox-mcp

Unofficial MCP (Model Context Protocol) server for DIDOX — the Uzbek e-document / e-invoicing (ЭСФ) platform.

It turns the DIDOX REST API into a set of tools that any MCP client — Claude Desktop, Claude Code, Cursor, etc. — can call directly. Ask your assistant "покажи входящие счета-фактуры за неделю" and it queries DIDOX for you.

Disclaimer: this is an unofficial, community-maintained project. It is not affiliated with, endorsed by, or supported by DIDOX. Use at your own risk; verify anything important in the DIDOX cabinet.

Status: read tools (documents, profile, company lookups, catalogs) + unsigned draft writes (create/update/delete). Signing/sending is out of scope (needs ЭЦП). No document creation or signing yet (see Roadmap).

Installation

# from a checkout
uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python -e .

# or plain pip
pip install -e .

Python 3.12+ is required. The didox-mcp console script (stdio transport) is installed as the entry point.

Configuration

Everything is configured through environment variables:

Variable	Required	Description
DIDOX_TIN	yes	Your company TIN (ИНН) used to log in
DIDOX_PASSWORD	yes*	DIDOX account password (password login flow)
DIDOX_TOKEN	yes*	Alternative: a pre-issued user-key token; skips password login (note: DIDOX tokens expire after 360 minutes and a static token is not auto-refreshed)
DIDOX_ENVIRONMENT	no	test (default), development or production — see hosts below
DIDOX_PARTNER_TOKEN	no	Partner API token; sent as the Partner-Authorization header whenever set
DIDOX_LOCALE	no	ru (default) or uz

* at least one of DIDOX_PASSWORD / DIDOX_TOKEN is required.

DIDOX_ENVIRONMENT	Host	Notes
test	https://testapi3.didox.uz	Sandbox; works with user-key alone, no partner token needed
development	https://stage.goodsign.biz	Partner staging; partner token required
production	https://api-partners.didox.uz	Partner production; partner token required

The server logs in lazily with the password flow, caches the token and refreshes it automatically before the 360-minute TTL lapses — staying friendly to the DIDOX login rate limit (repeated failed logins block the account for ~10 minutes).

Connecting an MCP client

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "didox": {
      "command": "didox-mcp",
      "env": {
        "DIDOX_ENVIRONMENT": "test",
        "DIDOX_TIN": "000000000",
        "DIDOX_PASSWORD": "your-password"
      }
    }
  }
}

Use the absolute path to the script (e.g. /path/to/.venv/bin/didox-mcp) if didox-mcp is not on Claude Desktop's PATH.

Claude Code

claude mcp add didox \
  -e DIDOX_ENVIRONMENT=test \
  -e DIDOX_TIN=000000000 \
  -e DIDOX_PASSWORD=your-password \
  -- didox-mcp

More clients and details: docs/usage.md.

Tools

Tool	What it does
didox_list_documents	List incoming (owner=0) / outgoing (owner=1) documents with filters: status, doctype, partner TIN, date range
didox_get_document	Full details of one document by id
didox_document_statistics	Document counts per status code
didox_get_pdf	Download the printable PDF to a temp file; returns path + size (inline base64 only on request and under 100 KB)
didox_get_profile	Your own company profile / requisites
didox_company_info	Any organization's details by TIN or PINFL
didox_vat_status	VAT registration status of a taxpayer (optionally as of a date)
didox_list_banks	Bank classifier
didox_list_measures	Measure units (ru/uz)
didox_list_regions	Regions of Uzbekistan
didox_list_districts	Districts
didox_create_document	Create a new document as an unsigned draft (doctype + payload)
didox_update_draft	Update an existing unsigned draft
didox_delete_draft	Delete an unsigned draft

Status codes in DIDOX are document-type-specific (for an invoice 3 means "Подписан", for a letter the same 3 means "Прочитано"). Every tool response therefore includes both the numeric code and a doctype-aware human-readable label.

Security

• Credentials live only in environment variables on your machine; the server runs locally over stdio and talks exclusively to the configured DIDOX host.
• Tokens and passwords are never logged or echoed in error messages.
• .env files are git-ignored; never commit credentials.

Roadmap

• v0.2 — drafts: create / update / delete documents, contract templates.
• v0.3 — signing (accept / reject / cancel) via a local E-IMZO bridge. Honest caveat: DIDOX documents no headless/server-side signing — a running local E-IMZO with your key will be required.
• v0.4 — streamable HTTP transport with authentication.

Development

uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest -q     # tests (network mocked)
.venv/bin/ruff check .            # lint

See CONTRIBUTING.md. Endpoint notes (own words, no copied docs): docs/api-notes.md. Architecture and rationale: docs/DESIGN.md.

License

Apache-2.0. Copyright 2026 Sanjar Usman (see NOTICE).