mcp-egrul

MCP server (Model Context Protocol — an open protocol for connecting AI assistants to external tools) for working with EGRUL (Unified State Register of Legal Entities of the Russian Federation) and EGRIP (Unified State Register of Individual Entrepreneurs). Source — official open-data dumps from the FTS (Federal Tax Service).

Status: v0.1.2 — open version (self-host via SQLite) is fully ready + hosted Pro client side (HTTP client HostedClient for api.atomno.ru). Published on PyPI, indexed in Glama and Smithery. The hosted Pro infrastructure itself is in active development. Coverage 100.00% (345 tests, ruff clean, fastmcp 3.2.4, enforced via --cov-fail-under=100).

Companion project: mcp-fns-check (risk-check layer over EGRUL).

What it is

Seven MCP tools visible to an AI assistant (Cursor, Claude Desktop, Cline, any MCP client):

Plus a diagnostic ping to check if the server is alive.

Full payload specification — in src/mcp_egrul/schemas.py (Pydantic models CompanyCard, IECard, SearchResult, BulkResult).

Related MCP server: onec-meta-mcp

Installation

Option 1 — via PyPI (recommended for users)

# Без локального clone — работает «из коробки»
uvx atomno-mcp-egrul

# Или установка глобально
pipx install atomno-mcp-egrul
atomno-mcp-egrul

# Или классический pip в venv
pip install atomno-mcp-egrul
atomno-mcp-egrul

Option 2 — dev-mode (for developers)

Requires Python 3.11+ and uv (fast pip replacement, optional).

git clone https://github.com/atomno-labs/mcp-egrul
cd mcp-egrul
uv venv
uv pip install -e ".[dev]"

Alternatively via pip:

python -m venv .venv
.venv/Scripts/activate    # Windows
# source .venv/bin/activate  # Linux/macOS
pip install -e ".[dev]"

Running

atomno-mcp-egrul

Default transport is stdio (standard input/output JSON-RPC). Suitable for connecting to Cursor / Claude Desktop / Claude Code.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "egrul": {
      "command": "uvx",
      "args": ["atomno-mcp-egrul"]
    }
  }
}

Cursor (.cursor/mcp.json in the project or ~/.cursor/mcp.json globally)

{
  "mcpServers": {
    "egrul": {
      "command": "uvx",
      "args": ["atomno-mcp-egrul"]
    }
  }
}

If you are not using uv, replace "command": "uvx", "args": ["atomno-mcp-egrul"] with "command": "atomno-mcp-egrul" (requires pip install atomno-mcp-egrul or pipx install atomno-mcp-egrul).

Docker (self-host) — quick start

# 1. Скачайте дампы ФНС (acceptance на сайте ФНС — раз в жизни).
#    Источники:
#      ЕГРЮЛ — https://www.nalog.gov.ru/opendata/7707329152-egrul/
#      ЕГРИП — https://www.nalog.gov.ru/opendata/7707329152-egrip/
#    Положите их в структуру:
mkdir -p dumps/egrul/2026-04-24 dumps/egrip/2026-04-24
cp ~/Downloads/EGRUL_*.zip dumps/egrul/2026-04-24/
cp ~/Downloads/EGRIP_*.zip dumps/egrip/2026-04-24/

# 2. Первоначальный полный импорт (однократно, ~30-60 минут):
docker compose --profile import run --rm \
    mcp-egrul-import atomno-mcp-egrul-import --registry egrul --full
docker compose --profile import run --rm \
    mcp-egrul-import atomno-mcp-egrul-import --registry egrip --full

# 3. Запустите сервер + фоновый cron-демон:
docker compose up -d
docker compose logs -f mcp-egrul-scheduler

About 10 minutes after import, all tools (search_by_inn, search_by_name, etc.) will respond with data from the local FTS snapshot.

Volume schema /data inside the container:

/data/
├── mcp_egrul_data.sqlite     # SQLite + FTS5
└── dumps/                    # read-only монтируется из ./dumps
    ├── egrul/
    │   └── YYYY-MM-DD/*.zip
    └── egrip/
        └── YYYY-MM-DD/*.zip

Cron-daemon (atomno-mcp-egrul-scheduler) automatically fetches the freshest dump after you place it in dumps/<registry>/<YYYY-MM-DD>/ — at night at 03:00 Europe/Moscow. If there is nothing new, the job will finish with nothing_to_import and will not make any unnecessary entries in import_log.

Importing FTS dumps (manual mode)

Sources:

• EGRUL open-data: https://www.nalog.gov.ru/opendata/7707329152-egrul/

• EGRIP open-data: https://www.nalog.gov.ru/opendata/7707329152-egrip/

Format: daily XML archives in ZIP, ~15 GB for a full snapshot. Legally, you must download them from the FTS website after accepting the license — the server does not download archives itself (strictly).

CLI:

# Полный первоначальный импорт (однократно):
atomno-mcp-egrul-import --registry egrul --full
atomno-mcp-egrul-import --registry egrip --full

# Инкремент (cron / ручной): загружается только если появилась более
# свежая YYYY-MM-DD-папка, чем последний успешный `import_log.source_dump_date`.
# Если новее нет — exit-code 5 и сообщение `nothing_to_import`.
atomno-mcp-egrul-import --registry egrul --incremental

# Фоновой cron-демон с ежедневным 03:00 MSK (вызывать вручную редко;
# обычно запускается сервисом mcp-egrul-scheduler в docker-compose).
atomno-mcp-egrul-scheduler --run-now

Exit-codes atomno-mcp-egrul-import:

Pro / hosted-mode (proxy to api.atomno.ru)

When the user sets ATOMNO_API_KEY, all seven tools are automatically proxied to the hosted Pro API (SPEC §5.4, §5.4.1). Local SQLite is not used in this mode — hosted Pro provides:

• Up-to-date data for today (without the daily delay of open-data dumps): direct scrape of egrul.nalog.ru + Dadata fallback on the server side.

• Bulk-endpoint without rate-limit (POST /companies/bulk) — one request instead of N local gathers.

• AI-summary of the card, change history, search by director's full name (Pro-only tools — arrive with the hosted server in Phase 2, see §5.4.1).

Price: Pro — $10/mo separately or $15/mo bundled with mcp-fns-check (bundle-key). Free tier: 30 requests/day/IP without registration (SPEC §1).

Configuration in Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "egrul": {
      "command": "uvx",
      "args": ["atomno-mcp-egrul"],
      "env": {
        "ATOMNO_API_KEY": "your-pro-key-here"
      }
    }
  }
}

Behavior and errors — no silent fallback: if the hosted API is unavailable, the client raises a typed exception instead of silently returning data from an outdated local dump. Mapping HTTP ↔ MCP error code — in SPEC §5.4.1:

INN/OGRN validation remains client-side (check digits are verified before the HTTP request — saving round-trip on invalid identifiers).

Configuration (environment variables)

Example — see .env.example.

Structure

apps/mcp-egrul/
├── pyproject.toml
├── LICENSE                             # MIT
├── README.md                           # ЭТОТ ФАЙЛ
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
├── src/mcp_egrul/
│   ├── __init__.py
│   ├── server.py                       # FastMCP entrypoint, регистрация 7 тулзов + ping
│   ├── context.py                      # ServiceContext (DI: SQLiteStore + HTTP-клиент)
│   ├── config.py                       # Чтение env-vars в типизированные поля
│   ├── constants.py                    # Все магические числа и enum'ы
│   ├── validators.py                   # Контрольные цифры ИНН (10/12) и ОГРН (13/15)
│   ├── schemas.py                      # Pydantic-модели CompanyCard/IECard/SearchResult/...
│   ├── errors.py                       # McpEgrulError и подклассы
│   ├── db/
│   │   ├── __init__.py
│   │   └── sqlite.py                   # Async-клиент (aiosqlite), init/query/upsert/search + import_log
│   ├── sources/
│   │   ├── __init__.py
│   │   ├── base.py                     # Абстрактный интерфейс Source
│   │   ├── opendata.py                 # ФНС open-data адаптер (read-local → SQLite upsert)
│   │   ├── opendata_parser.py          # Потоковый lxml.iterparse парсер ЕГРЮЛ/ЕГРИП XML
│   │   └── hosted_adapter.py           # HTTP-клиент hosted Pro API (SPEC §5.4.1)
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── search_by_inn.py
│   │   ├── search_by_ogrn.py
│   │   ├── search_by_name.py
│   │   ├── get_full_card.py
│   │   ├── get_founders.py
│   │   ├── get_director.py
│   │   └── bulk_cards.py
│   └── scripts/
│       ├── __init__.py
│       ├── import_opendata.py          # CLI `atomno-mcp-egrul-import` (ручной / одноразовый)
│       └── scheduler.py                # CLI `atomno-mcp-egrul-scheduler` (apscheduler cron 03:00 MSK)
└── tests/
    ├── __init__.py
    ├── conftest.py
    ├── fixtures/
    │   ├── egrul_sample.xml            # Мини-ЕГРЮЛ (2 валидных + 1 skip на неизвестный статус)
    │   └── egrip_sample.xml            # Мини-ЕГРИП (active + closed)
    ├── test_validators.py
    ├── test_schemas.py
    ├── test_config.py                  # Config.from_env + _parse_float_env (валидация env)
    ├── test_sqlite_store.py
    ├── test_cards.py                   # _cards.py: parse_iso_date/datetime + build_*card
    ├── test_server_ping.py             # FastMCP tool-layer + server.main()
    ├── test_tools.py                   # 7 тулзов: happy-path + validation + not_found
    ├── test_opendata_parser.py         # XML-парсер (zip, xml, skip-на-неизвестный-статус)
    ├── test_opendata_source.py         # OpenDataSource.run_ingest (full/incremental)
    ├── test_integration_import.py      # Полный цикл import → search → get_card
    ├── test_import_cli.py              # CLI `atomno-mcp-egrul-import`
    ├── test_scheduler_cli.py           # CLI `atomno-mcp-egrul-scheduler` + _run_scheduler
    └── test_hosted_adapter.py          # HostedClient + маршрутизация тулзов (respx-моки)

Tests

pytest -v --cov=src/mcp_egrul

Current coverage: 100.00% (345 tests passed, ruff clean, 1529 statements + 382 branches, 0 misses). Enforced by --cov-fail-under=100 policy — any regression will break CI. Tests cover:

• INN/OGRN/OGRNIP validators (check digits);

• Config.from_env + float-env-variable parser (validation, not silent fallback);

• all 7 MCP tools (happy-path + validation + not_found + bulk partial);

• SQLite store + FTS5 + import_log;

• XML-parser for EGRUL/EGRIP (zip, xml, skip-record with unknown status);

• OpenDataSource.run_ingest (full/incremental/nothing_to_import);

• full integration cycle import fixture → search → get_card → bulk;

• both CLIs (atomno-mcp-egrul-import, atomno-mcp-egrul-scheduler) — cron-job registration, argument parsing, _run_daily_ingest on all-happy/nothing_to_import/McpEgrulError, full cycle _run_scheduler with mock-ed asyncio.Event;

• FastMCP tool-layer via mcp.call_tool() — error serialization into structured dicts, server.main() with valid and invalid env;

• HostedClient (hosted Pro API proxy) — happy-path of all 7 methods, all HTTP errors from SPEC §5.4.1 (401/403/404/413/429/5xx), timeout/ConnectError, invalid JSON/payload from server, client-side bulk validation, async with-context; plus routing from tools in hosted-mode (when ATOMNO_API_KEY is set — request goes to api.atomno.ru, not SQLite, INN validation before HTTP);

• edge-cases of XML-parser (75 separate unit-tests on _parse_company/_parse_ie/_parse_share/_parse_director/_parse_founders/address fallbacks/legacy-attributes/invalid INN/OGRN/KPP lengths);

• private SQLite-store helpers (_wrap, _prepare_row, _row_to_dict, _normalize_bm25, auto-init via _ensure, rejecting invalid finish_import statuses);

• ServiceContext reentry-idempotency, atexit-cleanup, Config.from_env ValidationError → exit-code 2 from atomno-mcp-egrul-import CLI.

External APIs are never called directly from tests — only via respx (HTTP-mocking) and local XML-fixtures (tests/fixtures/).

Security and legal status

• All sources are publicly open FTS data (EGRUL / EGRIP open-datasets), the distribution of which is permitted by the Federal Law "On Information..." and EGRUL-specific norms (see SPEC §8).

• Legal entities do not fall under 152-FZ (On Personal Data).

• Full names of individual directors and founders are published by the FTS itself in the open registry — forwarding this data is legal.

• No write-operations to any external API.

• Secrets — only via environment variables, in the repository — .env.example without values.

Disclaimer

The service is an aggregator and a convenient interface over public FTS data. Not affiliated with the FTS. Use at your own risk. Information in the service's responses is not a substitute for a full legal or financial assessment.

License

MIT. LICENSE file in the root folder.