mcp-egrul

mcp-egrul

ЕГРЮЛ 和 ЕГРИП MCP 服务：通过税务机关公开数据查询俄罗斯公司和个体经营者的详细信息。可在本地安装，也可连接到 Cursor、Claude 和任何 MCP 客户端。

面向 AI Agent 的俄罗斯公司注册信息查询。

状态： v0.1.2 — 开源版（通过 SQLite 自托管）已完全就绪 + hosted Pro 客户端部分已完成（面向 api.atomno-mcp.ru 的 HTTP 客户端 HostedClient）。已发布到 PyPI，并已被 Glama 和 Smithery 收录。hosted Pro 基础设施仍在积极开发中。Coverage 100.00%（345 个测试，ruff 检查通过，fastmcp 3.2.4，通过 --cov-fail-under=100 强制执行）。

配套项目： mcp-fns-check（基于 ЕГРЮЛ 的风险检查层）。

---

这是什么

七个 AI 助手（Cursor、Claude Desktop、Cline、任何 MCP 客户端）可调用的 MCP 工具：

工具	描述	参数
search_by_inn	按 ИНН 搜索（10 位 — 法人，12 位 — 个体经营者）	inn: str
search_by_ogrn	按 ОГРН（13 位）或 ОГРНИП（15 位）搜索	ogrn: str
search_by_name	按名称模糊搜索（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（推荐用户使用）

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

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

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

方式 2 — 开发模式（供开发者使用）

需要 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（自托管）— 快速开始

# 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/<registry>/<YYYY-MM-DD>/ 后自动获取它——于夜间 03:00 Europe/Moscow 执行。如果没有新数据，任务将以 nothing_to_import 结束， 且不会向 import_log 写入多余记录。

---

导入 ФНС 转储文件（手动模式）

来源：

• ЕГРЮЛ 开放数据： https://www.nalog.gov.ru/opendata/7707329152-egrul/
• ЕГРИП 开放数据： https://www.nalog.gov.ru/opendata/7707329152-egrip/

格式：每日 XML ZIP 压缩包；完整快照约 15 GB。根据法规，必须在接受许可协议后从 ФНС 网站下载——服务器不会自行下载压缩包（严格遵守）。

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

atomno-mcp-egrul-import 的退出代码：

代码	含义
0	导入成功
2	配置 / CLI 参数无效
4	数据导入错误（XML 损坏、没有转储目录、DB 错误）
5	nothing_to_import — 数据库中已有最新日期的数据（增量导入）

---

Pro / 托管模式（代理到 api.atomno-mcp.ru）

当用户设置 ATOMNO_API_KEY 时，全部七个工具都会自动代理到托管 Pro API（SPEC §5.4、§5.4.1）。此模式下不会使用本地 SQLite；托管 Pro 提供：

• 截至今日的最新数据（没有开放数据转储的每日延迟）：服务器端直接抓取 egrul.nalog.ru，并在必要时回退到 Dadata。
• 不受速率限制的批量端点（POST /companies/bulk）——一次请求即可替代 N 次本地 gather。
• AI 摘要卡片、变更历史、按董事姓名搜索（Pro 专属工具将随 Phase 2 的托管服务一并提供，参见 §5.4.1）。

价格：Pro 单独订阅为 $10/月，与 mcp-fns-check 组合订阅为 $15/月（捆绑密钥）。免费层级：无需注册，每个 IP 每天 30 次请求（SPEC §1）。

在 Cursor 中配置（.cursor/mcp.json）：

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

行为与错误——不会静默回退：如果托管 API 不可用，客户端会抛出类型化异常，而不会悄悄返回过时本地转储中的数据。HTTP 状态码与 MCP 错误代码的对应关系见 SPEC §5.4.1：

托管 API 的 HTTP 响应	客户端异常	error.code
200	—	—
400	ValidationError	invalid_input
401	HostedAuthError	auth_required
403	ProRequiredError	pro_required
404（code=not_found）	NotFoundError	not_found
404（路由错误）	SourceUnavailableError	source_unavailable
413	BulkTooLargeError	bulk_too_large
429	RateLimitedError（含 Retry-After）	rate_limit
5xx	SourceUnavailableError	source_unavailable
超时 / DNS 失败	SourceUnavailableError（cause=timeout/ConnectError）	source_unavailable

ИНН/ОГРН 的校验仍在客户端进行（在 HTTP 请求前检查校验位，以免为无效标识符浪费往返时间）。

---

配置（环境变量）

变量	描述	默认值
MCP_EGRUL_DB	ЕГРЮЛ/ЕГРИП 快照 SQLite 文件的路径	./mcp_egrul_data.sqlite
MCP_EGRUL_USER_AGENT	HTTP 客户端的 User-Agent	mcp-egrul/0.1 (+https://github.com/atomno-mcp/mcp-egrul)
MCP_EGRUL_HTTP_TIMEOUT	HTTP 超时时间（秒）	30
MCP_EGRUL_DUMPS_DIR	ФНС 转储目录，结构为 <dir>/<registry>/<YYYY-MM-DD>/*.zip	./dumps
MCP_EGRUL_LOG_LEVEL	日志级别	INFO
TZ	scheduler 的时区（cron 03:00）	Europe/Moscow
ATOMNO_API_KEY	（Pro）托管订阅密钥——启用代理到 api.atomno-mcp.ru	未设置
ATOMNO_API_BASE	（Pro）托管 API 的基础 URL	https://api.atomno-mcp.ru/mcp-egrul/v1

示例见 .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              # CLI `atomno-mcp-egrul-import`
    ├── test_scheduler_cli.py           # CLI `atomno-mcp-egrul-scheduler` + _run_scheduler
    └── test_hosted_adapter.py          # HostedClient + маршрутизация тулзов (respx-моки)

---

测试

pytest -v --cov=src/mcp_egrul

当前覆盖率：100.00%（345 tests passed，ruff 检查通过，1529 条语句 + 382 个分支，0 misses）。由 --cov-fail-under=100 强制执行——任何回归都会导致 CI 失败。测试覆盖：

• ИНН/ОГРН/ОГРНИП 验证器（校验位）；
• Config.from_env + float 环境变量解析器（进行验证，而非静默回退）；
• 全部 7 个 MCP 工具（正常路径 + 验证 + not_found + 批量部分成功）；
• SQLite 存储 + FTS5 + import_log；
• ЕГРЮЛ/ЕГРИП XML 解析器（zip、xml、跳过状态未知的记录）；
• OpenDataSource.run_ingest（完整/增量/nothing_to_import）；
• 完整集成流程 import fixture → search → get_card → bulk；
• 两个 CLI（atomno-mcp-egrul-import、atomno-mcp-egrul-scheduler）——注册 cron 任务、解析参数、在 all-happy/nothing_to_import/McpEgrulError 情况下运行 _run_daily_ingest，以及通过 mock 的 asyncio.Event 完整运行 _run_scheduler；
• 通过 mcp.call_tool() 测试 FastMCP 工具层——将错误序列化为结构化 dict、使用有效和无效环境变量运行 server.main()；
• HostedClient（托管版 Pro API 代理）——全部 7 个方法的正常路径、SPEC §5.4.1 中的全部 HTTP 错误（401/403/404/413/429/5xx）、超时/ConnectError、来自服务的无效 JSON/payload、客户端批量验证、async with 上下文；以及托管模式下从工具到 API 的路由（设置 ATOMNO_API_KEY 时，请求会发送到 api.atomno-mcp.ru，而不是 SQLite；发送 HTTP 请求前验证 ИНН）；
• XML 解析器的边界情况（针对 _parse_company/_parse_ie/_parse_share/_parse_director/_parse_founders/地址回退/旧版属性/无效 ИНН/ОГРН/КПП 长度编写的 75 个独立单元测试）；
• SQLite 存储的私有辅助函数（_wrap、_prepare_row、_row_to_dict、_normalize_bm25、通过 _ensure 自动初始化、拒绝无效的 finish_import 状态）；
• ServiceContext 重入幂等性、atexit 清理，以及 Config.from_env 的 ValidationError → atomno-mcp-egrul-import CLI 退出码 2。

测试绝不会直接调用外部 API——只使用 respx（HTTP 模拟）和本地 XML 测试样例（tests/fixtures/）。

---

安全与法律状态

• 所有来源均为俄罗斯联邦税务局公开数据（ЕГРЮЛ / ЕГРИП 开放数据集），根据联邦法律《信息……》及 ЕГРЮЛ 相关规定允许传播（参见 SPEC §8）。
• 法人实体不受 152-ФЗ（《个人数据法》）约束。
• 负责人和创始人的个人姓名由俄罗斯联邦税务局自行发布在公开登记册中；转发这些数据合法。
• 不会向任何外部 API 执行写入操作。
• 密钥仅通过环境变量提供；仓库中仅有不含实际值的 .env.example。

---

免责声明

本服务是俄罗斯联邦税务局公开数据的聚合器和便捷界面。与俄罗斯联邦税务局无关联。使用风险由您自行承担。服务回复中的信息不能替代完整的法律或财务评估。

---

许可证

MIT。文件 LICENSE 位于文件夹根目录。