mcp-fns-check

Purpose

mcp-fns-check is a Model Context Protocol (MCP) server for due diligence and business intelligence gathering on Russian counterparties. Its starting point is that AI agents (Claude, Cursor, etc.) usually do not know about Russian counterparties — ЕГРЮЛ is poorly indexed by search engines, ФНС "Прозрачный бизнес" data is hidden behind POST requests and CAPTCHA, and ЕФРСБ returns only HTML. This server provides agents with 7 tools; a complete profile can be obtained in a single call.

Main capabilities

Through tool calls, the following information can be obtained:

• Entity identity: name, address, ОКВЭД (economic activity classification), head.
• Status: operating, in liquidation, bankrupt, deregistered, reorganized.
• Cooperation safety: mass addresses, mass heads, disqualification, bankruptcy, tax arrears, enforcement proceedings, arbitration cases.

The core tool is check_contractor(identifier), which accepts ИНН or ОГРН and returns an aggregated report with a verdict, whose possible values are safe_to_proceed / manual_review_required / high_risk_do_not_proceed / impossible_contractor_defunct, along with a list of specific recommendations.

Public data sources used

• egrul.nalog.ru — ЕГРЮЛ/ЕГРИП, counterparty card.
• bankrot.fedresurs.ru — ЕФРСБ (Unified Federal Register of Bankruptcy Information).
• ФНС open data, dataset "debtam" — tax arrears (local export).
• service.nalog.ru — real-time register of disqualified persons.
• fssp.gov.ru — ФССП enforcement proceedings database.
• kad.arbitr.ru — arbitration case card index.
• Local slice of ФНС registers — mass addresses, mass heads, disqualified persons (loaded from ФНС Open Data via the atomno-mcp-fns-etl script).

It does not include a check for "failure to submit tax returns": there is no public source for this information, and the service will not answer "filed" when there is no data.

How to use

By default it runs as a stdio-MCP server: the agent communicates with it via JSON-RPC over stdin/stdout, and it cannot be used directly by "clicking" from a shell; it must be connected to an MCP client. For network scenarios, --transport {http,sse,streamable-http} and the --host / --port parameter are provided. It can also be run via uv / pipx.

Connecting to an MCP client:

• Cursor: edit mcp.json(Settings → Cursor Settings → MCP), restart Cursor. In the chat, ask "Проверь контрагента ИНН 7707083893", and the agent will automatically call check_contractor.
• Claude Desktop: edit claude_desktop_config.json（macOS：~/Library/Application Support/Claude/；Windows：%APPDATA%\Claude\), restart Claude Desktop.
• Claude Code (CLI) and Cline (VS Code): configure in cline_mcp_settings.json .

All configuration is done through environment variables; no credentials are required (all data sources are public). See .env.examplefor a template.

Local ФНС registers

The mass address / head registers are CSV exports of ФНС open data. When the export files are not loaded, these checks answer "not performed" and do not affect the verdict as if the data source had responded. The distribution contains only the teaching file registries_seed.jsonfor testing, and the server will not load it into the working database.

To use them for actual checks, load the slices via CLI atomno-mcp-fns-etl :

• Mass addresses → nalog.gov.ru/opendata/7707329152-masaddress/
• Mass heads → nalog.gov.ru/opendata/7707329152-massleaders/
• Disqualified persons → service.nalog.ru/disqualified.do

This CLI runs by default as --dry-run (parses and prints a sample); writing requires explicitly adding --commit. Meta fields <registry>.last_etl、<registry>.last_etl_source、<registry>.last_etl_count is automatically saved and can be used as cron data freshness monitoring.

In tests, external APIs are never called directly—only via respx (mock httpx) + tests/fixtures/ local fixed data.

Failure behavior

• ЕГРЮЛ is the only blocking data source. If unavailable,check_contractor raises SourceUnavailableError(the agent receives a human-readable message).
• The remaining data sources are best-effort: ФССП CAPTCHA, КАД antibot,pb.nalog.ru 5xx will be logged to risks.errors[], will not fail the report, but the top-level verdict becomes manual_review_required.

Limitations and known issues

• No history for officers: ФНС does not provide change history via the search API; full history will appear after loading the ЕГРЮЛ Open Data slice (planned for v0.5+).
• ЕФРСБ (legal entity bankruptcy) is protected by Qrator for programmatic queries (403 / "human or robot" verification), and automated checks often cannot be completed; this is recorded in the report as a data source error, not as "no bankruptcy". There is no ready-made workaround; official Федресурс access is needed, or manual checking in bankrot.fedresurs.ru .
• ФССП public search returns a window with an image CAPTCHA; the code does not bypass it: the check truthfully falls into errors[], reason captcha_required.
• КАД returns 451 for programmatic search (DDoS-Guard protection). This is not a certificate error: the site is signed by Let's Encrypt. Official access belongs to the card file operator. In the report it is recorded as "not checked", not as "no litigation".
• If some checks do not respond, the final risk level is "undetermined" (unknown), not "low". An empty flags[] by itself does not equal "clean".
• Tax arrears come from ФНС open data (the "debtam" dataset): they include the arrears amount, penalties, and fines, but are published as a snapshot by report date, not in real time. For actual amounts, rely on the ИФНС certificate.
• The local ФНС register (bulk addresses, bulk officers, disqualification) must be loaded regularly. If the export is empty or outdated, the check truthfully answers "not checked" and goes into errors[]; it will not give "no match" based on outdated data.
• Failure to file tax returns is not checked—there is no public source.
• Regarding Pro-tier (atomno-mcp-fns-check-server managed backend, closed source): the above limitations are eliminated through Redis 24h caching, proxy rotation to bypass CAPTCHA, a full ЕГРЮЛ Open Data slice, batch checks of up to 100 ИНН, and AI-summary via LLM. The backend itself is not public.

Security and legal status

• All data sources are public data from ФНС and related registers. Use is lawful under Federal Law No. 149-FZ "On Information".
• Federal Law No. 152-FZ (Personal Data Law) does not apply to legal entities or individual entrepreneurs.
• The names of natural-person officers are published by ФНС in ЕГРЮЛ; in outbound responses, the ИНН of natural-person officers is masked (format XXX*****YY).
• No write operations are performed against external APIs.
• No credential / token is required—the data sources are fully public.
• This service is an aggregator and convenience interface over ФНС public data and is not affiliated with ФНС Russia, ЕФРСБ, КАД, or ФССП. Use at your own risk.
• Information in the service response cannot replace a full legal or financial assessment. Whether to enter into a contract with a counterparty is your decision.

License: MIT (see LICENSE).