mcp-egrul

MCP-Server (Model Context Protocol — ein offenes Protokoll zur Anbindung von KI-Assistenten an externe Tools) für die Arbeit mit EGRUL (Einheitliches Staatliches Register juristischer Personen der RF) und EGRIP (Einheitliches Staatliches Register von Einzelunternehmern). Quelle — offizielle Open-Data-Dumps des FTS (Föderaler Steuerdienst).

Status: v0.1.2 — Open-Version (Self-Host über SQLite) vollständig fertiggestellt + Client-Teil hosted Pro (HTTP-Client HostedClient für api.atomno.ru). Veröffentlicht auf PyPI, indexiert in Glama und Smithery. Die hosted Pro-Infrastruktur befindet sich in aktiver Entwicklung. Coverage 100.00% (345 Tests, ruff clean, fastmcp 3.2.4, erzwungen durch --cov-fail-under=100).

Partnerprojekt: mcp-fns-check (Risiko-Check-Ebene über EGRUL).

Was ist das

Sieben MCP-Tools, die für den KI-Assistenten (Cursor, Claude Desktop, Cline, jeder MCP-Client) sichtbar sind:

Plus ein diagnostischer ping, um zu prüfen, ob der Server läuft.

Die vollständige Spezifikation der Payloads befindet sich in src/mcp_egrul/schemas.py (Pydantic-Modelle CompanyCard, IECard, SearchResult, BulkResult).

Related MCP server: onec-meta-mcp

Installation

Variante 1 — über PyPI (empfohlen für Benutzer)

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

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

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

Variante 2 — Dev-Modus (für Entwickler)

Erfordert Python 3.11+ und uv (schneller Ersatz für pip, optional).

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

Alternativ über pip:

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

Start

atomno-mcp-egrul

Der Standardtransport ist stdio (Standard-Ein-/Ausgabe JSON-RPC). Geeignet für die Verbindung mit Cursor / Claude Desktop / Claude Code.

Claude Desktop (claude_desktop_config.json)

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

Cursor (.cursor/mcp.json im Projekt oder ~/.cursor/mcp.json global)

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

Wenn Sie kein uv verwenden, ersetzen Sie "command": "uvx", "args": ["atomno-mcp-egrul"] durch "command": "atomno-mcp-egrul" (erfordert pip install atomno-mcp-egrul oder 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

Etwa 10 Minuten nach dem Import antworten alle Tools (search_by_inn, search_by_name etc.) bereits mit Daten aus dem lokalen FTS-Abbild.

Schema des Volumes /data innerhalb des Containers:

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

Der Cron-Daemon (atomno-mcp-egrul-scheduler) holt sich selbstständig den neuesten Export, nachdem Sie ihn unter dumps/<registry>/<YYYY-MM-DD>/ abgelegt haben — nachts um 03:00 Uhr Europe/Moscow. Wenn nichts Neues vorhanden ist, beendet sich der Job mit nothing_to_import und nimmt keine unnötigen Einträge in import_log vor.

Import von FTS-Dumps (manueller Modus)

Quellen:

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

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

Format: Tägliche XML-Archive in ZIP, ca. 15 GB für ein vollständiges Abbild. Rechtlich müssen diese von der FTS-Website nach Akzeptanz der Lizenz heruntergeladen werden — der Server lädt die Archive nicht selbst herunter (strikt).

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 von atomno-mcp-egrul-import:

Pro / Hosted-Modus (Proxy auf api.atomno.ru)

Wenn der Benutzer ATOMNO_API_KEY angibt, werden alle sieben Tools automatisch auf die hosted Pro API (SPEC §5.4, §5.4.1) weitergeleitet. Das lokale SQLite wird in diesem Modus nicht verwendet — die hosted Pro bietet:

• Aktuelle Daten für heute (ohne die tägliche Verzögerung des Open-Data-Dumps): direkter Scrape von egrul.nalog.ru + Dadata-Fallback auf Serverseite.

• Bulk-Endpoint ohne Rate-Limit (POST /companies/bulk) — eine Anfrage statt N lokaler Gather-Operationen.

• AI-Summary der Karteikarte, Änderungshistorie, Suche nach dem Namen des Geschäftsführers (Pro-only Tools — kommen zusammen mit dem hosted-Server in Phase 2, siehe §5.4.1).

Preis: Pro — $10/Monat einzeln oder $15/Monat im Paket mit mcp-fns-check (Bundle-Key). Free Tier: 30 Anfragen/Tag/IP ohne Registrierung (SPEC §1).

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

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

Verhalten und Fehler — kein Silent Fallback: Wenn die hosted API nicht verfügbar ist, löst der Client eine typisierte Exception aus, anstatt stillschweigend Daten aus einem veralteten lokalen Dump auszugeben. Die Zuordnung HTTP ↔ MCP-Fehlercode finden Sie in SPEC §5.4.1:

Die Validierung von INN/OGRN bleibt Client-seitig (Prüfziffern werden vor der HTTP-Anfrage geprüft — Einsparung von Round-Trips bei fehlerhaften Identifikatoren).

Konfiguration (Umgebungsvariablen)

Beispiel — siehe .env.example.

Struktur

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

Aktuelle Coverage: 100.00% (345 tests passed, ruff clean, 1529 statements + 382 branches, 0 misses). Erzwungen durch die Richtlinie --cov-fail-under=100 — jede Regression bricht das CI. Die Tests decken ab:

• Validatoren für INN/OGRN/OGRNIP (Prüfziffern);

• Config.from_env + Parser für Float-Umgebungsvariablen (Validierung, kein Silent Fallback);

• alle 7 MCP-Tools (Happy-Path + Validierung + not_found + bulk partial);

• SQLite Store + FTS5 + import_log;

• XML-Parser für EGRUL/EGRIP (zip, xml, skip-Eintrag mit unbekanntem Status);

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

• vollständiger Integrationszyklus import fixture → search → get_card → bulk;

• beide CLI (atomno-mcp-egrul-import, atomno-mcp-egrul-scheduler) — Registrierung von Cron-Jobs, Argument-Parsing, _run_daily_ingest bei all-happy/nothing_to_import/McpEgrulError, vollständiger Zyklus _run_scheduler mit mock-ed asyncio.Event;

• FastMCP Tool-Layer über mcp.call_tool() — Serialisierung von Fehlern in strukturierte Dicts, server.main() mit gültigem und ungültigem Env;

• HostedClient (hosted Pro API Proxy) — Happy-Path aller 7 Methoden, alle HTTP-Fehler aus SPEC §5.4.1 (401/403/404/413/429/5xx), timeout/ConnectError, ungültiges JSON/Payload vom Server, Client-seitige Bulk-Validierung, async with-Kontext; plus Routing von Tools im hosted-Modus (bei gesetztem ATOMNO_API_KEY — Anfrage geht an api.atomno.ru, nicht an SQLite, INN-Validierung vor HTTP);

• Edge-Cases des XML-Parsers (75 separate Unit-Tests für _parse_company/_parse_ie/_parse_share/_parse_director/_parse_founders/address fallbacks/legacy-Attribute/ungültige Längen von INN/OGRN/KPP);

• private Helper des SQLite-Stores (_wrap, _prepare_row, _row_to_dict, _normalize_bm25, auto-init über _ensure, Ablehnung ungültiger finish_import-Status);

• ServiceContext Reentry-Idempotenz, atexit-Cleanup, Config.from_env ValidationError → Exit-Code 2 aus atomno-mcp-egrul-import CLI.

Externe APIs werden niemals direkt aus den Tests aufgerufen — nur über respx (HTTP-Mocking) und lokale XML-Fixtures (tests/fixtures/).

Sicherheit und rechtlicher Status

• Alle Quellen sind öffentlich zugängliche Daten des FTS (EGRUL / EGRIP Open-Datasets), deren Verbreitung durch das FZ „Über Information…“ und EGRUL-spezifische Normen erlaubt ist (siehe SPEC §8).

• Juristische Personen fallen nicht unter das 152-FZ (Über personenbezogene Daten).

• Die Namen von Geschäftsführern und Gründern werden vom FTS selbst im offenen Register veröffentlicht — die Übermittlung dieser Daten ist legal.

• Keine Schreiboperationen an irgendeine externe API.

• Geheimnisse — nur über Umgebungsvariablen, im Repository — .env.example ohne Werte.

Disclaimer

Der Dienst ist ein Aggregator und eine komfortable Schnittstelle für öffentliche Daten des FTS. Nicht mit dem FTS verbunden. Nutzung auf eigene Gefahr. Die Informationen in den Antworten des Dienstes sind kein Ersatz für eine vollständige rechtliche oder finanzielle Bewertung.

Lizenz

MIT. Datei LICENSE im Stammverzeichnis des Ordners.