mcp-egrul

MCP-сервер (Model Context Protocol — открытый протокол подключения AI-ассистентов к внешним инструментам) для работы с ЕГРЮЛ (Единый Государственный Реестр Юридических Лиц РФ) и ЕГРИП (Единый Государственный Реестр Индивидуальных Предпринимателей). Источник — официальные open-data дампы ФНС (Федеральной налоговой службы).

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

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

# Без локального clone — работает «из коробки» uvx atomno-mcp-egrul # Или установка глобально pipx install atomno-mcp-egrul atomno-mcp-egrul # Или классический pip в venv pip install atomno-mcp-egrul atomno-mcp-egrul

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

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

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

Транспорт по умолчанию —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).

# 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/ ├── 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/<registry>/<YYYY-MM-DD>/— ночью в 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 лицензии— сервер не качает архивы сам (строго).

# Полный первоначальный импорт (однократно): 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

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

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

- Актуальные данные на сегодня(без суточной задержки open-data дампа): прямой scrapeegrul.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 на битых идентификаторах).

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-моки)

Текущий coverage:100.00%(345 tests passed, ruff clean, 1529 statements + 382 branches,0 misses). Enforced политикой--cov-fail-under=100— любая регрессия сломает CI. Тесты покрывают:

- валидаторы ИНН/ОГРН/ОГРНИП (контрольные цифры);
- Config.from_env+ парсер float-env-переменных (валидация, а не silent fallback);
- все 7 MCP-тулзов (happy-path + validation + not_found + bulk partial);
- SQLite store + FTS5 +import_log;
- XML-парсер ЕГРЮЛ/ЕГРИП (zip, xml, skip-запись с неизвестным статусом);
- OpenDataSource.run_ingest(full/incremental/nothing_to_import);
- полный интеграционный циклimport fixture → search → get_card → bulk;
- обе CLI (atomno-mcp-egrul-import,atomno-mcp-egrul-scheduler) — регистрация cron-job'ов, парсинг аргументов,_run_daily_ingestна all-happy/nothing_to_import/McpEgrulError, полный цикл_run_schedulerс mock-edasyncio.Event;
- FastMCP tool-layer черезmcp.call_tool()— сериализация ошибок в структурированные dict'ы,server.main()с валидным и невалидным env;
- HostedClient(hosted Pro API proxy) — happy-path всех 7 методов, все HTTP-ошибки из SPEC §5.4.1 (401/403/404/413/429/5xx), timeout/ConnectError, невалидный JSON/payload от сервера, клиентская валидация bulk,async with-контекст; плюс маршрутизация из тулзов в hosted-режиме (при заданATOMNO_API_KEY— запрос идёт вapi.atomno-mcp.ru, не в SQLite, валидация ИНН до HTTP);
- edge-case'ы XML-парсера (75 отдельных unit-тестов на_parse_company/_parse_ie/_parse_share/_parse_director/_parse_founders/address fallback'ы/legacy-атрибуты/ невалидные длины ИНН/ОГРН/КПП);
- приватные helper'ы SQLite-стора (_wrap,_prepare_row,_row_to_dict,_normalize_bm25, auto-init через_ensure, rejecting invalidfinish_importстатусов);
- ServiceContextreentry-идемпотентность,atexit-cleanup,Config.from_envValidationError → exit-code 2 изatomno-mcp-egrul-importCLI.

Внешние APIникогда не вызываются напрямуюиз тестов — только черезrespx(HTTP-мокинг) и локальные XML-фикстуры (tests/fixtures/).

- Все источники —публично открытые данные ФНС(ЕГРЮЛ / ЕГРИП open-datasets), распространение которых разрешено ФЗ «Об информации…» и ЕГРЮЛ-специфичными нормами (см. SPEC §8).
- Юридические лица не подпадают под 152-ФЗ (О персональных данных).
- ФИО физлиц-руководителей и учредителей публикуются самой ФНС в открытом реестре — пересылка этих данных легальна.
- Никаких write-операций ни в один внешний API.
- Секреты — только через переменные окружения, в репозитории —.env.exampleбез значений.

Сервис —агрегатор и удобный интерфейс над публичными данными ФНС. Не аффилирован с ФНС. Используется на ваш риск. Информация в ответах сервиса не является заменой полноценной юридической или финансовой оценки.

Verify US/Canada freight carriers and brokers: live FMCSA data, trust scores, registry search, and partner watchlist monitoring for AI agents.

CLI and MCP server for the UK Companies House API — company search, profiles, officers, filings, ownership, and due diligence

All-in-one bundle: EU VAT validation, Dutch CBS statistics, and GDPR compliance tools — 19 tools for EU businesses in a single MCP server.

Ask natural language questions about your SafetyCulture data using the SafetyCulture API.

EU Corporate Sustainability Reporting Directive compliance — ESRS mapping, double materiality, ESG data collection by MEOK AI Labs

EU Corporate Sustainability Reporting Directive compliance — ESRS data points, double materiality assessments, audit trails, and XBRL-ready outputs for ESG reporting.

MCP-сервер налоговых/бухгалтерских калькуляторов ФНС + публичные фискальные статусы (самозанятый, ИП/ОКВЭД, дисквалификация, блокировки счетов). Волна 1, юр-риск минимальный.

KYB for AI agents: verify business registrations from MCP clients.

Company lookup, LEI search, SEC filings, and financials for AI agents. 6 tools, free, no API key.

Live MCP server connecting AI agents to 36+ business data sources. OAuth 2.1 PKCE.