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без значений.

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

Transaction-complete hotel booking over MCP — 300K+ properties, real hotel confirmation numbers, loyalty points, secure checkout. Hotels are merchant of record. Builders set their own booking fee via Stripe Connect. Built on proven distribution infrastructure.

An MCP server for AI video generation. MCP server for AI video generation. Lets Claude, ChatGPT, OpenClaw , Hermes & other agents create AI videos and publish them to YouTube, TikTok, Instagram etc..

Institutional research and manager diligence reports on hedge funds, venture capital and private equity managers. Summary of filings, personnel changes, media screening and social signals delivered to you in minutes.

ALTER - identity infrastructure for the AI economy

D2C eCommerce fulfillment platform: manage orders, inventory, shipments, campaigns, and billing via AI agents

Apigene MCP Gateway is the runtime layer that connects AI agents to APIs and MCP servers via Model Context Protocol.

MCP to interface with multiple blockchains, staking, DeFi, swap, bridging, wallet management, DCA, Limit Orders, Coin Lookup, Tracking and more.

MCP server for Bitnovo Pay integration with AI agents. Provides cryptocurrency payment capabilities through Bitnovo Pay API. Features include payment creation, status checking, QR code generation, and webhook management with support for multiple tunnel providers (ngrok, zrok, manual).

Shop for gift cards, esims, phone topups. Pay with cards and crypto.

You built it, now get users! GoToMarket MCP server