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.

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

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).

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:

• mass_addresses → nalog.gov.ru/opendata/7707329152-massreg/

• mass_directors → nalog.gov.ru/opendata/7707329152-massuchredt/

• disqualified → service.nalog.ru/disqualified.do

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.

Security and Legal Status

• 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.

Links

• GitHub: atomno-labs/mcp-fns-check

• More MCP servers under the atomno brand: atomno.ru catalog (coming soon)

• MCP specification: modelcontextprotocol.io