mcp-fns-check

<!-- mcp-name: io.github.atomno-mcp/mcp-fns-check --> # Tool List > MCP Server for checking Russian counterparties (legal entities and individual entrepreneurs) through public data of the Federal Taxation Service: USRLE/USRIP, EFRSB, "Transparent Business", Federal Bailiff Service, and Judicial Arbitration Cases.       Ready to connect to Claude Desktop, Cursor, Claude Code, Cline, and any other client compatible with Model Context Protocol (MCP). ## Purpose AI-agents (Claude, Cursor, etc.) usually know nothing about Russian counterparties: USRLE is not indexed by search engines properly, data in Transparent Business requires POST requests and CAPTCHA, and EFRSB returns HTML. This MCP Server provides the agent with **seven tools** to get a complete picture in one call: - Who is this: name, address, OKVED, and manager. - Is it alive: active, liquidation, bankruptcy, dissolved, or reorganization. - Is it safe to work with: mass address, mass manager, disqualification, bankruptcy, tax debts, failure to provide reporting, enforcement proceedings, and arbitration cases. The main tool is `check_contractor(identifier)` - it takes 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. ## Quick Start ### Installation ```bash pip install atomno-mcp-fns-check ``` Or via `uv` / `pipx`: ```bash uv pip install atomno-mcp-fns-check # or pipx install atomno-mcp-fns-check ``` ### Checking Work ```bash atomno-mcp-fns-check --version # → atomno-mcp-fns-check 0.1.1 atomno-mcp-fns-check --help # → full list of flags: --transport / --host / --port / --log-level ``` By default, the package runs as a stdio-MCP Server: the agent communicates with it through stdin/stdout JSON-RPC. You can't "poke" it directly from the shell - connect 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): ```json { "mcpServers": { "fns-check": { "command": "atomno-mcp-fns-check" } } } ``` Restart Cursor. In the chat, ask: "Check counterparty INN 7707083893" - the agent will call `check_contractor`. ### Claude Desktop Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`): ```json { "mcpServers": { "fns-check": { "command": "atomno-mcp-fns-check" } } } ``` Restart Claude Desktop. ### Claude Code (CLI) ```bash claude mcp add fns-check atomno-mcp-fns-check ``` ### Cline (VS Code) In `cline_mcp_settings.json`: ```json { "mcpServers": { "fns-check": { "command": "atomno-mcp-fns-check", "disabled": false, "autoApprove": [] } } } ``` ## Tools | Tool | Purpose | Input | Sources | |---|---|---|---| | **`check_contractor`** | **Main.** Full check by one identifier + determined verdict and recommendations | `identifier: str` (INN 10/12 or OGRN 13/15) | all 5 | | `check_inn` | Basic card of USRLE | `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` | USRLE + EFRSB | | `get_okveds` | OKVED codes with decoding | `inn` or `ogrn` | USRLE + OKVED-2 dictionary | | `get_directors_history` | Current manager (+ history as per Open Data) | `inn: str` | USRLE | | `check_for_red_flags` | 8 risk checks (4 basic + 4 extended) | `inn: str` | all 5 | Used public sources: - **egrul.nalog.ru** - USRLE/USRIP, counterparty card. - **bankrot.fedresurs.ru** - EFRSB (Unified Federal Register of Bankruptcy Information). - **pb.nalog.ru** - Transparent Business (tax debts, failure to provide reporting). - **fssp.gov.ru** - Federal Bailiff Service Data Bank. - **kad.arbitr.ru** - Judicial Arbitration Case Files. - Local slices of Federal Taxation Service registries - mass addresses, mass managers, disqualified persons (downloaded by `atomno-mcp-fns-etl` script from Open Data). ### Example Response `check_contractor` ```json { "identifier": "7707083893", "identifier_type": "inn", "inn": "7707083893", "ogrn": "1027700132195", "card": { "name": {"full": "SBERBANK", "short": "SBERBANK"}, "status": "active", "address": {"full": "117997, MOSCOW, VAVILOVA STREET, 19", "is_mass_address": false}, "director": {"full_name": "Gref G. O.", "position": "President"}, "okved_main": {"code": "64.19", "name": "Other monetary intermediation"} }, "legal_status": {"status": "active", "status_label_ru": "Active", "sources_checked": ["egrul", "efrsb"]}, "risks": {"overall_risk_level": "low", "overall_risk_score": 0, "flags": [], "errors": []}, "verdict_action": "safe_to_proceed", "verdict_reason_ru": "Status 'Active', risk level - low (score 0/100). No obstacles to conclude a deal according to open sources were found.", "recommendations": [ "No obstacles to conclude a deal were found according to open sources. Observe standard due diligence measures (Article 54.1 of the Tax Code): a copy of the charter, an order for the manager, an agreement." ], "sources": {"sources_queried": ["efrsb", "egrul", "fssp", "kad", "pb_fns", "registries"]}, "tier": "open", "checked_at": "2026-04-24T20:15:00Z" } ``` ### Behavior in Case of Source Failures - USRLE is the only **blocking** source. If it's unavailable, `check_contractor` raises `SourceUnavailableError` (the agent will receive a human-readable message). - Other sources are added **best-effort**: CAPTCHA on Federal Bailiff Service, antibot on Judicial Arbitration Cases, 5xx on pb.nalog.ru - all this is added to `risks.errors[]` and does not break the report. The top-level verdict becomes `manual_review_required`. ## Configuration All settings are made through environment variables. No credentials are required (sources are public). | Variable | Description | Default | |---|---|---| | `MCP_FNS_CACHE_DB` | Path to SQLite file of cached cards | `./atomno_mcp_fns_check_cache.sqlite` | | `MCP_FNS_REGISTRIES_DB` | Path to SQLite file of registries (mass addresses/managers/disqualifications) | `<cache>.registries.sqlite` | | `MCP_FNS_CACHE_TTL_HOURS` | TTL of cached cards, hours | `168` (7 days) | | `MCP_FNS_HTTP_TIMEOUT` | HTTP timeout, seconds | `15` | | `MCP_FNS_USER_AGENT` | User-Agent of HTTP client | `atomno-mcp-fns-check/0.1 (+https://github.com/atomno-mcp/mcp-fns-check)` | | `MCP_FNS_LOG_LEVEL` | Logging level (DEBUG/INFO/WARNING/ERROR) | `INFO` | Template - `.env.example`. ## Local Federal Taxation Service Registries Registries of mass addresses / managers / disqualified persons are CSV/XML dumps of Open Data. The package comes with a built-in mini-seed (`registries_seed.json`, synthetic test records) - it's enough for tools to work "out of the box" and show flags on test INN. For production checks, update registries with full slices using CLI `atomno-mcp-fns-etl`: ```bash 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/](https://www.nalog.gov.ru/opendata/7707329152-massreg/) - `mass_directors` → [nalog.gov.ru/opendata/7707329152-massuchredt/](https://www.nalog.gov.ru/opendata/7707329152-massuchredt/) - `disqualified` → [service.nalog.ru/disqualified.do](https://service.nalog.ru/disqualified.do) By default, CLI works in `--dry-run` (parses and prints sample); to write, you need an explicit `--commit`. 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 ```bash git clone https://github.com/atomno-mcp/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 through `respx` (mocking httpx) + local fixtures in `tests/fixtures/`. ## Limitations - **No history for executives** — The Federal Taxation Service (FNS) does not provide a history of changes through the search-API; the full history will be available after loading the Open Data slice of the Unified State Register of Legal Entities (planned for v0.5+). - **FSSP / KAD sometimes block** CAPTCHA / antibot. In this case, the check falls into `errors[]`, and the general verdict becomes `manual_review_required`. - **Transparent Business** only provides the fact (“there is a debt” / “no reporting”), without the amount. The amount must be requested from the Federal Taxation Service (FNS). The Pro-tier (hosted backend in `atomno-mcp-fns-check-server` — a private backend) removes these limitations through: 24h Redis cache, proxy rotation to bypass CAPTCHA, full Open Data slice of the Unified State Register of Legal Entities, batch checks up to 100 TIN, AI-summary via LLM. The backend itself is not published. --- ## Security and Legal Status - All sources are **publicly open data from the Federal Taxation Service (FNS)** and related registers. Usage is legal under the Federal Law No. 149-FZ “On Information”. - Legal entities and individual entrepreneurs **do not fall under** the Federal Law No. 152-FZ (On Personal Data). - The full names of physical persons-executives are published by the FNS in the Unified State Register of Legal Entities openly; in outbound responses, the TIN of the physical person-executive is masked (format `XXX*****YY`). - No write operations to any external API. - No credentials / tokens are required — sources are fully public. --- ## Disclaimer The service is **an aggregator and a convenient interface over public data from the Federal Taxation Service (FNS)**. Not affiliated with the FNS of Russia, EFRСБ, KAD, FSSP. Used at your own risk. The information in the service responses **does not replace** a full-fledged legal or financial assessment. The decision to enter into an agreement with a counterparty is made by you. --- ## License MIT — see `LICENSE`. --- ## Links - GitHub: [atomno-mcp/mcp-fns-check](https://github.com/atomno-mcp/mcp-fns-check) - More MCP servers under the atomno brand: [atomno-labs.ru catalog](https://atomno-labs.ru/) (soon) - MCP specification: [modelcontextprotocol.io](https://modelcontextprotocol.io)