atomno-mcp/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-клиент):
| Tool | Описание | Аргументы |
|---|---|---|
| search_by_inn | Поиск по ИНН (10 цифр — юр.лицо, 12 — ИП) | inn: str |
| search_by_ogrn | Поиск по ОГРН (13) или ОГРНИП (15) | ogrn: str |
| search_by_name | Fuzzy-поиск по названию (FTS5) | query: str, limit?: int, only_active?: bool |
| get_full_card | Полная карточка со всеми секциями | inn?: str, ogrn?: str |
| get_founders | Только учредители с долями | inn: str |
| get_director | Только текущий руководитель | inn: str |
| bulk_cards | Массовая проверка (до 100 ИНН) | inns: list[str] |
Плюс диагностический ping для проверки что сервер жив.
Полная спецификация payload'ов — в src/mcp_egrul/schemas.py (Pydantic-модели CompanyCard, IECard, SearchResult, BulkResult).
---
Установка
Вариант 1 — через PyPI (рекомендуется для пользователей)
Вариант 2 — dev-режим (для разработчиков)
Требуется Python 3.11+ и uv (быстрая замена pip, опционально).
Альтернативно через pip:
---
Запуск
Транспорт по умолчанию — **stdio** (стандартный ввод/вывод JSON-RPC). Подходит для подключения к Cursor / Claude Desktop / Claude Code.
Claude Desktop (claude_desktop_config.json)
Cursor (.cursor/mcp.json в проекте или ~/.cursor/mcp.json глобально)
> Если не используете 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
Через ~10 минут после импорта все тулзы (search_by_inn, search_by_name и пр.) уже отвечают данными из локального слепка ФНС.
Схема тома /data внутри контейнера:
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:
Exit-коды atomno-mcp-egrul-import:
| Код | Значение |
|---|---|
| 0 | Импорт прошёл успешно |
| 2 | Невалидный конфиг / аргумент CLI |
| 4 | Ошибка ингеста (битый XML, нет каталога дампов, DB error) |
| 5 | nothing_to_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'ов.