mcp-egrul

mcp-egrul

MCP-сервер ЕГРЮЛ и ЕГРИП: реквизиты российских компаний и ИП по открытым данным налоговой службы. Можно поставить у себя или подключить к Cursor, Claude и любому клиенту MCP.

Russian company registry lookup for AI agents.

Статус: v0.1.2 — open-версия (self-host через SQLite) полностью готова + клиентская часть hosted Pro (HTTP-клиент HostedClient для api.atomno-mcp.ru). Опубликована на PyPI, индексирована в Glama и Smithery. Сама hosted Pro-инфра — в активной разработке. Coverage `100.00%` (345 тестов, ruff clean, fastmcp 3.2.4, enforced через --cov-fail-under=100).

Парный проект: mcp-fns-check (risk-чек-слой поверх ЕГРЮЛ).

---

Что это

Семь MCP-тулзов, видимых AI-ассистенту (Cursor, Claude Desktop, Cline, любой MCP-клиент):

Плюс диагностический ping для проверки что сервер жив.

Полная спецификация payload'ов — в src/mcp_egrul/schemas.py (Pydantic-модели CompanyCard, IECard, SearchResult, BulkResult).

---

Установка

Вариант 1 — через PyPI (рекомендуется для пользователей)

# Без локального clone — работает «из коробки»

uvx atomno-mcp-egrul

Или установка глобально

pipx install atomno-mcp-egrul atomno-mcp-egrul

Или классический pip в venv

pip install atomno-mcp-egrul atomno-mcp-egrul

Вариант 2 — dev-режим (для разработчиков)

Требуется Python 3.11+ и uv (быстрая замена pip, опционально).

git clone https://github.com/atomno-mcp/mcp-egrul

cd mcp-egrul uv venv uv pip install -e ".[dev]"

Альтернативно через pip:

python -m venv .venv

.venv/Scripts/activate # Windows

source .venv/bin/activate # Linux/macOS

pip install -e ".[dev]"

---

Запуск

atomno-mcp-egrul

Транспорт по умолчанию — stdio (стандартный ввод/вывод JSON-RPC). Подходит для подключения к Cursor / Claude Desktop / Claude Code.

Claude Desktop (claude_desktop_config.json)

{

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

Cursor (.cursor/mcp.json в проекте или ~/.cursor/mcp.json глобально)

{

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

Если не используете uv, замените "command": "uvx", "args": ["atomno-mcp-egrul"] на "command": "atomno-mcp-egrul" (требует pip install atomno-mcp-egrul или 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

Через ~10 минут после импорта все тулзы (search_by_inn, search_by_name и пр.) уже отвечают данными из локального слепка ФНС.

Схема тома /data внутри контейнера:

/data/

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

Cron-демон (atomno-mcp-egrul-scheduler) сам забирает самую свежую выгрузку после того как вы положите её в dumps/ / / — ночью в 03:00 Europe/Moscow. Если ничего нового нет — job завершится с nothing_to_import и никаких лишних записей в import_log не сделает.

---

Импорт дампов ФНС (ручной режим)

Источники:

• ЕГРЮЛ open-data: https://www.nalog.gov.ru/opendata/7707329152-egrul/
• ЕГРИП open-data: https://www.nalog.gov.ru/opendata/7707329152-egrip/

Формат: суточные архивы XML в ZIP, ~15 ГБ на полный слепок. Юридически их нужно скачать с сайта ФНС после acceptance лицензии — сервер не качает архивы сам (строго).

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-коды atomno-mcp-egrul-import:

---

Pro / hosted-режим (прокси на api.atomno-mcp.ru)

Когда пользователь задаёт ATOMNO_API_KEY, все семь тулзов автоматически проксируются на hosted Pro API (SPEC §5.4, §5.4.1). Локальный SQLite в этом режиме не используется — hosted Pro даёт:

• Актуальные данные на сегодня (без суточной задержки open-data дампа): прямой scrape egrul.nalog.ru + Dadata fallback на стороне сервера.
• Bulk-эндпойнт без rate-limit (POST /companies/bulk) — один запрос вместо N локальных gather'ов.
• AI-summary карточки, история изменений, поиск по ФИО директора (Pro-only тулзы — приезжают вместе с hosted-сервером в Phase 2, см. §5.4.1).

Цена: Pro — $10/мес отдельно или $15/мес в паре с mcp-fns-check (bundle-ключ). Free tier: 30 запросов/день/IP без регистрации (SPEC §1).

Настройка в Cursor (.cursor/mcp.json):

{

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

Поведение и ошибки — никакого silent fallback: если hosted API недоступен, клиент поднимает типизированное исключение, а не молча отдаёт данные из устаревшего локального дампа. Сопоставление HTTP ↔ MCP-код ошибки — в SPEC §5.4.1:

Валидация ИНН/ОГРН остаётся клиент-саид (контрольные цифры проверяются до HTTP-запроса — экономия round-trip на битых идентификаторах).

---

Конфигурация (переменные окружения)

Пример — см. .env.example.

---

Структура

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