mcp-egrul

mcp-egrul

ЕГРЮЛ と ЕГРИП の MCP サーバー：税務当局のオープンデータに基づくロシア企業および個人事業主の登録情報です。自分の環境にインストールするか、Cursor、Claude、およびあらゆる MCP クライアントに接続できます。

AI エージェント向けのロシア企業登録情報検索ツールです。

ステータス： v0.1.2 — オープン版（SQLite を使ったセルフホスト）は完全に利用可能です。さらに、ホスト型 Pro のクライアント側（api.atomno-mcp.ru 用の HTTP クライアント HostedClient）も利用できます。 PyPI で公開され、Glama と Smithery に登録済みです。ホスト型 Pro のインフラ自体は現在開発中です。カバレッジ 100.00%（テスト 345 件、ruff クリーン、fastmcp 3.2.4、--cov-fail-under=100 で強制）。

関連プロジェクト： mcp-fns-check（ЕГРЮЛ 上に構築されたリスクチェックレイヤー）。

---

概要

AI アシスタント（Cursor、Claude Desktop、Cline、任意の MCP クライアント）から利用できる 7 つの 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 もあります。

ペイロードの完全な仕様は 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 など）がローカルの FNS スナップショットのデータを返すようになります。

コンテナ内の /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 に余分な記録は作成されません。

---

FNS ダンプのインポート（手動モード）

データソース：

• ЕГРЮЛ オープンデータ： https://www.nalog.gov.ru/opendata/7707329152-egrul/
• ЕГРИП オープンデータ： https://www.nalog.gov.ru/opendata/7707329152-egrip/

形式：日次の XML ZIP アーカイブ。スナップショット全体で約 15 GB です。法的要件により、ライセンスに同意した後、FNS のウェブサイトからダウンロードする必要があります。サーバーはアーカイブを自動ダウンロードしません（厳守）。

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 — 最新の日付がすでに DB に存在します（増分処理）

---

Pro／ホステッドモード（api.atomno-mcp.ruへのプロキシ）

ユーザーがATOMNO_API_KEYを設定すると、7つすべてのツールが自動的にホステッドPro APIにプロキシされます（SPEC §5.4、§5.4.1）。このモードではローカルのSQLiteは使用されません。ホステッドProでは次の機能を利用できます。

• 本日時点の最新データ（オープンデータダンプの1日遅れなし）：サーバー側でegrul.nalog.ruを直接スクレイピングし、Dadataをフォールバックとして使用します。
• レート制限のないバルクエンドポイント（POST /companies/bulk）：ローカルでのN回の並列取得の代わりに、1回のリクエストで取得できます。
• AIサマリーカード、変更履歴、代表者の氏名による検索（Pro限定ツールはPhase 2でホステッドサーバーとともに提供されます。§5.4.1を参照）。

料金：Proは単体で月額$10、またはmcp-fns-checkとのセットで月額$15（バンドルキー）です。Free tier：登録不要でIPあたり1日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 (wrong route)	SourceUnavailableError	source_unavailable
413	BulkTooLargeError	bulk_too_large
429	RateLimitedError（Retry-After付き）	rate_limit
5xx	SourceUnavailableError	source_unavailable
timeout / DNS fail	SourceUnavailableError（cause=timeout／ConnectError）	source_unavailable

INN／OGRNの検証は引き続きクライアント側で行われます（HTTPリクエストの前にチェックディジットを検証し、無効な識別子による往復通信を省きます）。

---

設定（環境変数）

変数	説明	デフォルト
MCP_EGRUL_DB	EGRUL／EGRIPのスナップショットを格納する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	FNSダンプのディレクトリ。構造は<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 statements + 382 branches、未カバー箇所 0）。--cov-fail-under=100 ポリシーで強制されており、回帰があると CI が失敗します。テストでは以下をカバーします。

• INN／OGRN／OGRNIP のバリデーター（チェックデジット）；
• Config.from_env と float 型環境変数パーサー（サイレントフォールバックではなく、バリデーションを実施）；
• MCP ツール 7 個すべて（正常系＋バリデーション＋not_found＋一部失敗を含む一括処理）；
• SQLite ストア＋FTS5＋import_log；
• ЕГРЮЛ／ЕГРИП の XML パーサー（zip、xml、不明なステータスによるレコードのスキップ）；
• OpenDataSource.run_ingest（全件／増分／nothing_to_import）；
• 統合サイクル全体（import fixture → search → get_card → bulk）；
• 2 つの CLI（atomno-mcp-egrul-import、atomno-mcp-egrul-scheduler）— cron ジョブの登録、引数の解析、正常系／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／ペイロード、一括処理のクライアント側バリデーション、async with コンテキスト；さらにホステッドモードでのツールからのルーティング（ATOMNO_API_KEY が設定されている場合、リクエストは SQLite ではなく api.atomno-mcp.ru に送信されること、HTTP の前に INN が検証されること）；
• XML パーサーのエッジケース（_parse_company／_parse_ie／_parse_share／_parse_director／_parse_founders／住所のフォールバック／レガシー属性／無効な INN／OGRN／KPP の長さに対する個別の単体テスト 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-FZ（個人データに関する法律）の適用対象ではありません。
• 経営者および設立者である個人の氏名は、ФНС 自身が公開登録簿で公表しているため、これらのデータを送信することは合法です。
• 外部 API への書き込み操作は一切ありません。
• シークレットは環境変数のみを使用し、リポジトリには値のない .env.example を置いています。

---

免責事項

本サービスは、ФНС の公開データを集約し、使いやすいインターフェースを提供するものです。ФНС とは無関係です。ご自身の責任でご利用ください。本サービスの回答に含まれる情報は、正式な法的または財務的評価の代わりにはなりません。

---

ライセンス

MIT。ルートフォルダー内の LICENSE ファイルをご覧ください。