Skip to main content
Glama

atomno-mcp-fns-check

MCP server for verifying Russian counterparties (legal entities and individual entrepreneurs) via public Federal Tax Service data: EGRUL/EGRIP, EFRSB, "Transparent Business", FSSP, and KAD.

build version license mcp tests coverage

Ready to be connected to Claude Desktop, Cursor, Claude Code, Cline, and any other client compatible with the Model Context Protocol (MCP).


Why

An AI agent (Claude, Cursor, etc.) usually knows nothing about Russian counterparties: EGRUL is not indexed properly by search engines, data in the FNS Transparent Business portal is behind POST requests and CAPTCHA, and EFRSB provides HTML. This MCP server gives the agent seven tools through which it can get a complete picture in a single call:

  • Who they are: name, address, OKVED, director.

  • Status: active, in liquidation, bankruptcy, liquidated, reorganization.

  • Is it safe to work with them: mass address, mass director, disqualification, bankruptcy, tax debts, failure to file reports, enforcement proceedings, arbitration cases.

The main tool — check_contractor(identifier) — accepts an INN or OGRN and returns an aggregated report with a verdict (safe_to_proceed / manual_review_required / high_risk_do_not_proceed / impossible_contractor_defunct) and a list of specific recommendations.


Related MCP server: mcp-egrul

Quick Start

Installation

pip install atomno-mcp-fns-check

Or via uv / pipx:

uv pip install atomno-mcp-fns-check
# или
pipx install atomno-mcp-fns-check

Verifying Operation

atomno-mcp-fns-check --version
# → atomno-mcp-fns-check 0.1.1

atomno-mcp-fns-check --help
# → полный список флагов: --transport / --host / --port / --log-level

By default, the package runs as a stdio-MCP server: the agent communicates with it via stdin/stdout JSON-RPC. You cannot "poke" it directly from the shell — connect it to an MCP client. For network scenarios, the --transport {http,sse,streamable-http} flag is available with --host/--port.


Connecting to MCP Clients

Cursor

Edit mcp.json (Cursor → Settings → Cursor Settings → MCP):

{
  "mcpServers": {
    "fns-check": {
      "command": "atomno-mcp-fns-check"
    }
  }
}

Restart Cursor. In the chat, ask: "Check counterparty INN 7707083893" — the agent will call check_contractor itself.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "fns-check": {
      "command": "atomno-mcp-fns-check"
    }
  }
}

Restart Claude Desktop.

Claude Code (CLI)

claude mcp add fns-check atomno-mcp-fns-check

Cline (VS Code)

In cline_mcp_settings.json:

{
  "mcpServers": {
    "fns-check": {
      "command": "atomno-mcp-fns-check",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Tools

Tool

Purpose

Input

Sources

check_contractor

Main. Full check by a single identifier + deterministic verdict and recommendations

identifier: str (INN 10/12 or OGRN 13/15)

all 5

check_inn

Basic EGRUL card

inn: str

egrul.nalog.ru

check_ogrn

Basic card by OGRN/OGRNIP

ogrn: str

egrul.nalog.ru

get_legal_status

Life status with enrichment

inn or ogrn

EGRUL + EFRSB

get_okveds

OKVED codes with descriptions

inn or ogrn

EGRUL + OKVED-2 dictionary

get_directors_history

Current director (+ history as per Open Data)

inn: str

EGRUL

check_for_red_flags

8 risk checks (4 basic + 4 extended)

inn: str

all 5

Public sources used:

  • egrul.nalog.ru — EGRUL/EGRIP, counterparty card.

  • bankrot.fedresurs.ru — EFRSB (Unified Federal Register of Bankruptcy Information).

  • pb.nalog.ru — FNS Transparent Business (tax debts, failure to file reports).

  • fssp.gov.ru — FSSP Enforcement Proceedings Data Bank.

  • kad.arbitr.ru — Arbitration Case File.

  • Local FNS registry slices — mass addresses, mass directors, disqualified persons (loaded by the atomno-mcp-fns-etl script from FNS Open Data).

Example check_contractor response

{
  "identifier": "7707083893",
  "identifier_type": "inn",
  "inn": "7707083893",
  "ogrn": "1027700132195",
  "card": {
    "name": {"full": "ПАО СБЕРБАНК", "short": "СБЕРБАНК"},
    "status": "active",
    "address": {"full": "117997, Г.Москва, УЛ. ВАВИЛОВА, Д. 19", "is_mass_address": false},
    "director": {"full_name": "Греф Г. О.", "position": "Президент"},
    "okved_main": {"code": "64.19", "name": "Денежное посредничество прочее"}
  },
  "legal_status": {"status": "active", "status_label_ru": "Действующее", "sources_checked": ["egrul", "efrsb"]},
  "risks": {"overall_risk_level": "low", "overall_risk_score": 0, "flags": [], "errors": []},
  "verdict_action": "safe_to_proceed",
  "verdict_reason_ru": "Статус «Действующее», уровень риска — low (score 0/100). Препятствий к заключению сделки по открытым источникам не найдено.",
  "recommendations": [
    "По открытым источникам препятствий к заключению сделки не обнаружено. Соблюдайте стандартные меры должной осмотрительности (ст. 54.1 НК РФ): копия устава, приказ на руководителя, договор."
  ],
  "sources": {"sources_queried": ["efrsb", "egrul", "fssp", "kad", "pb_fns", "registries"]},
  "tier": "open",
  "checked_at": "2026-04-24T20:15:00Z"
}

Behavior during source failures

  • EGRUL is the only blocking source. If it is unavailable, check_contractor raises SourceUnavailableError (the agent will receive a human-readable message).

  • Other sources are mixed in on a best-effort basis: CAPTCHA on FSSP, antibot on KAD, 5xx on pb.nalog.ru — everything is collected in risks.errors[] and does NOT crash the report. The high-level verdict becomes manual_review_required.


Configuration

All settings are via environment variables. No credentials are required (sources are public).

Variable

Description

Default

MCP_FNS_CACHE_DB

Path to the SQLite cache file

./atomno_mcp_fns_check_cache.sqlite

MCP_FNS_REGISTRIES_DB

Path to the SQLite registry file (mass addresses/directors/disqualifications)

<cache>.registries.sqlite

MCP_FNS_CACHE_TTL_HOURS

TTL for cached cards, hours

168 (7 days)

MCP_FNS_HTTP_TIMEOUT

HTTP timeout, seconds

15

MCP_FNS_USER_AGENT

HTTP client User-Agent

atomno-mcp-fns-check/0.1 (+https://github.com/atomno-labs/mcp-fns-check)

MCP_FNS_LOG_LEVEL

Logging level (DEBUG/INFO/WARNING/ERROR)

INFO

Template — .env.example.


Local FNS Registries

Registries of mass addresses / directors / disqualified persons are CSV/XML dumps from FNS Open Data. The package comes with a built-in mini-seed (registries_seed.json, synthetic test records) — it is enough for the tools to work "out of the box" and show flags on test INNs.

For production checks, update the registries with full slices via the atomno-mcp-fns-etl CLI:

atomno-mcp-fns-etl --registry mass_addresses --source ./fns_open_data/ulm.csv --commit
atomno-mcp-fns-etl --registry mass_directors --source ./fns_open_data/uchredt.csv --commit
atomno-mcp-fns-etl --registry disqualified --source ./fns_open_data/disqualified.csv --commit

Open Data sources:

By default, the CLI runs in --dry-run (parses and prints a sample); for writing, an explicit --commit is required. Meta-fields <registry>.last_etl, <registry>.last_etl_source, <registry>.last_etl_count are saved automatically — use them for cron monitoring of data freshness.


Development

git clone https://github.com/atomno-labs/mcp-fns-check
cd mcp-fns-check
python -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv/Scripts/activate     # Windows
pip install -e ".[dev]"
pytest -v --cov=src/atomno_mcp_fns_check

External APIs in tests are never called directly — only via respx (httpx mocking) + local fixtures in tests/fixtures/.


Limitations

  • No history for directors — FNS does not provide change history via the search API; full history will appear after loading the EGRUL Open Data slice (planned for v0.5+).

  • FSSP / KAD sometimes block via CAPTCHA / antibot. In this case, the check falls into errors[], and the overall verdict becomes manual_review_required.

  • Transparent Business only provides the fact ("has debt" / "no reporting"), without the amount. The amount must be requested from the IFNS.

Pro-tier (hosted backend in atomno-mcp-fns-check-server — closed backend) removes these limitations via: 24h Redis cache, proxy rotation to bypass CAPTCHA, full EGRUL Open Data slice, batch checks up to 100 INNs, AI-summary via LLM. The backend itself is not published.


  • All sources are publicly open FNS data and related registries. Use is legal under Federal Law 149-FZ "On Information".

  • Legal entities and individual entrepreneurs do not fall under 152-FZ (On Personal Data).

  • Full names of individual directors are published by the FNS in EGRUL openly; in outbound responses, the director's personal INN is masked (format XXX*****YY).

  • No write operations to any external API.

  • No credentials / tokens required — sources are completely public.


Disclaimer

The service is an aggregator and a convenient interface over public FNS data. It is not affiliated with the FNS of Russia, EFRSB, KAD, or FSSP. Use at your own risk.

Information in the service's responses does not replace a full legal or financial assessment. The decision to enter into a contract with a counterparty is yours.


License

MIT — see LICENSE.


Available Tools

8 tools
check_contractorA

Главный тул: полная проверка контрагента по одному идентификатору.

Принимает ИНН (10 цифр — юр.лицо, 12 — ИП/физлицо) или ОГРН (13 цифр — юр.лицо, 15 — ИП). Тип определяется строго по длине и контрольной цифре.

Inputs: identifier (required), include_extended_risks, lawsuits_threshold_rub. Returns: object

check_for_red_flagsA

Агрегированный риск-чек по контрагенту (8 проверок, SPEC §3.5).

Базовые 4 проверки (всегда):

  • mass_address — массовый юр.адрес ФНС;

  • mass_director — массовый руководитель (≥10 действующих компаний);

  • disqualified_director — руководитель в реестре дисквалифицированных;

  • bankruptcy_records — активные дела в ЕФРСБ.

Расширенные 4 проверки (include_extended=True):

  • tax_debts — индикатор задолженности по налогам (Прозрачный бизнес);

  • no_reporting — нет налоговой отчётности > 1 года (Прозрачный бизнес);

  • enforcement_proceedings — открытые исп.производства (Банк данных ФССП);

  • active_lawsuits — активные арбитражные дела где контрагент ответчик (КАД), фильтр по сумме иска через lawsuits_threshold_rub.

Любая внешняя проверка может вернуть ошибку (CAPTCHA, 5xx, timeout) — она попадёт в errors[] и не сорвёт остальные проверки.

Inputs: inn (required), include_extended, lawsuits_threshold_rub. Returns: object

check_innA

Полная карточка контрагента по ИНН (10 цифр — юр.лицо, 12 — ИП).

Inputs: inn (required), include_extended. Returns: object

check_ogrnC

Карточка контрагента по ОГРН (13 цифр) или ОГРНИП (15 цифр).

Inputs: ogrn (required), include_extended. Returns: object

get_directors_historyA

История смены руководителей и учредителей по ИНН.

На стадии S3 возвращает только текущего руководителя из egrul.nalog.ru плюс предупреждение о неполноте данных. Полная история (с датами назначения/увольнения) появится на стадии S5 после загрузки Open Data slice ЕГРЮЛ.

Inputs: inn (required), depth_years, include_founders. Returns: object

get_okvedsC

Перечень кодов ОКВЭД основной + дополнительные с расшифровкой по справочнику ОКВЭД-2.

Inputs: inn, ogrn, include_history. Returns: object

pingA

Диагностический тул: проверяет, что сервер запущен и доступен.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of contractor verification: comprehensive checks by identifier, risk flags, specific identifier lookups, director history, legal status, OKVED codes, and a diagnostic ping. No overlap in purpose.

    Naming Consistency4/5

    Tools follow a consistent snake_case pattern with clear verb prefixes (check_, get_, ping). Minor deviation with 'check_for_red_flags' using 'for', but overall pattern is predictable.

    Tool Count5/5

    8 tools is well-scoped for the domain of Russian contractor verification, covering all essential operations without being excessive or too sparse.

    Completeness4/5

    Covers core lifecycle: identifier validation, comprehensive checks, risk assessment, director history, legal status, and OKVED codes. Minor gaps like batch operations, but the main workflows are complete.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Central Bank of Russia (CBR) data for AI agents — daily and historical currency rates, key rate, inflation, and macro statistics. Five typed MCP tools, in-memory TTL cache, MIT-licensed, no API key required.
      5
      84 PyPI
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for the Russian state registries EGRUL (legal entities) and EGRIP (individual entrepreneurs), built on official Federal Tax Service open-data dumps. Self-hosted via local SQLite.
      8
      78 PyPI
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that provides 31 tools for the DaData API, enabling address autocomplete, company lookup, bank details, phone/email/passport validation, car recognition, geocoding, and reference directory queries.
      31
      7 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for verifying Polish business entities from the National Court Register (KRS) and VAT White List. Allows querying by KRS, NIP, or REGON to retrieve official company data including name, address, board, and capital.
      Apache 2.0