mcp-fns-check

MCP-servidor para verificação de contrapartes russas (pessoas jurídicas e empreendedores individuais) através de dados públicos da Receita Federal Russa (FNS): EGRUL/EGRIP, EFRBS, "Negócio Transparente", FSSP, KAD.

GitHub

Experimente este MCPPatrocinado

Documentação

atomno-mcp-fns-check

Servidor MCP para verificação de contrapartes russas: EGRUL, falência, dívidas fiscais, oficiais de justiça e processos arbitrais. Para inteligência de empresas — conecta-se ao Cursor, Claude e qualquer cliente MCP.

Verificação de contrapartes russas para agentes de IA.

Pronto para conexão no Claude Desktop, Cursor, Claude Code, Cline e qualquer outro cliente compatível com Model Context Protocol (MCP).

Por quê

Um agente de IA (Claude, Cursor, etc.) normalmente não sabe nada sobre contrapartes russas: o EGRUL não é indexado adequadamente pelos mecanismos de busca, os dados no Negócio Transparente da Receita Federal estão atrás de requisições POST e CAPTCHA, e o EFRSB entrega HTML. Este servidor MCP dá ao agente sete ferramentas, através das quais ele obtém o quadro completo em uma única chamada:

Quem é: nome, endereço, OKVED, dirigente.
Está ativo: em operação, em liquidação, falência, liquidado, reorganização.
É seguro trabalhar com ele: endereço em massa, dirigente em massa, inabilitação, falência, dívidas fiscais, processos de execução, processos arbitrais.

A ferramenta principal — check_contractor(identifier) — recebe INN ou OGRN e retorna um relatório agregado com veredito (safe_to_proceed / manual_review_required / high_risk_do_not_proceed / impossible_contractor_defunct) e uma lista de recomendações específicas.

Início rápido

Instalação

pip install atomno-mcp-fns-check

Ou via uv / pipx:

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

Verificação de funcionamento

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

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

Por padrão, o pacote é executado como servidor MCP stdio: o agente se comunica com ele via stdin/stdout JSON-RPC. Você não consegue "testá-lo" diretamente do shell — conecte-o a um cliente MCP. Para cenários de rede, está disponível a flag --transport {http,sse,streamable-http} com --host/--port.

Conexão a clientes MCP

Cursor

Edite o arquivo mcp.json (Cursor → Settings → Cursor Settings → MCP):

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

Reinicie o Cursor. No chat, pergunte: "Verifique a contraparte INN 7707083893" — o agente chamará check_contractor automaticamente.

Claude Desktop

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

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

Reinicie o Claude Desktop.

Claude Code (CLI)

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

Cline (VS Code)

Em cline_mcp_settings.json:

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

Ferramentas

Ferramenta	Finalidade	Entrada	Fontes
`check_contractor`	Principal. Verificação completa por um único identificador + veredito determinístico e recomendações	`identifier: str` (INN 10/12 ou OGRN 13/15)	todas as 5
`check_inn`	Cartão básico do EGRUL	`inn: str`	egrul.nalog.ru
`check_ogrn`	Cartão básico por OGRN/OGRNIP	`ogrn: str`	egrul.nalog.ru
`get_legal_status`	Status de vida com enriquecimento	`inn` ou `ogrn`	EGRUL + EFRSB
`get_okveds`	Códigos OKVED com descrição	`inn` ou `ogrn`	EGRUL + dicionário OKVED-2
`get_directors_history`	Dirigente atual (+ histórico conforme Open Data)	`inn: str`	EGRUL
`check_for_red_flags`	7 verificações de risco (4 básicas + 3 avançadas)	`inn: str`	todas as fontes

Fontes públicas utilizadas:

egrul.nalog.ru — EGRUL/EGRIP, cartão da contraparte.
bankrot.fedresurs.ru — EFRSB (Cadastro Federal Único de Informações sobre Falências).
Dados abertos da Receita Federal, conjunto "debtam" — dívidas fiscais (download local).
service.nalog.ru — cadastro ativo de pessoas inabilitadas.
fssp.gov.ru — Banco de dados de processos de execução do FSSP.
kad.arbitr.ru — Arquivo de processos arbitrais.
Snapshots locais dos cadastros da Receita Federal — endereços em massa, dirigentes em massa, pessoas inabilitadas (carregados pelo script atomno-mcp-fns-etl a partir dos Open Data da Receita Federal).

Verificações de não apresentação de declarações fiscais não estão no conjunto: não existe fonte pública dessas informações, e o serviço não responderá "declarações apresentadas" sem dados.

Exemplo de resposta do `check_contractor`

{
  "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"
}

Comportamento em falhas de fontes

EGRUL — única fonte blocking. Se estiver indisponível, check_contractor levanta SourceUnavailableError (o agente receberá uma mensagem legível).
As demais fontes são misturadas em modo best-effort: CAPTCHA no FSSP, antibot no KAD, 5xx no pb.nalog.ru — tudo é acumulado em risks.errors[] e NÃO derruba o relatório. O veredito de nível superior torna-se manual_review_required.

Configuração

Todas as configurações são feitas por variáveis de ambiente. Nenhuma credencial é necessária (as fontes são públicas).

Variável	Descrição	Padrão
`MCP_FNS_CACHE_DB`	Caminho para o arquivo SQLite de cache de cartões	diretório de dados do usuário (`%LOCALAPPDATA%/atomno/` ou `~/.local/share/atomno/`), não a pasta do projeto
`MCP_FNS_REGISTRIES_DB`	Caminho para o arquivo SQLite de cadastros (endereços/dirigentes em massa, inabilitações)	`<cache>.registries.sqlite`
`MCP_FNS_CACHE_TTL_HOURS`	TTL dos cartões em cache, em horas	`168` (7 dias)
`MCP_FNS_HTTP_TIMEOUT`	Timeout HTTP, em segundos	`15`
`MCP_FNS_USER_AGENT`	User-Agent do cliente HTTP	`atomno-mcp-fns-check/0.1 (+https://github.com/atomno-mcp/mcp-fns-check)`
`MCP_FNS_LOG_LEVEL`	Nível de log (DEBUG/INFO/WARNING/ERROR)	`INFO`

Modelo — .env.example.

Cadastros locais da Receita Federal

Os cadastros de endereços/dirigentes em massa são exportações CSV dos dados abertos da Receita Federal. Sem a exportação carregada, essas verificações respondem "não executada" e não influenciam o veredito como se a fonte tivesse respondido. O pacote inclui um arquivo de exemplo registries_seed.json apenas para testes; o servidor não o carrega no banco de produção.

Para verificações em produção, carregue os snapshots via CLI atomno-mcp-fns-etl:

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

Fontes Open Data:

mass_addresses → nalog.gov.ru/opendata/7707329152-masaddress/
mass_directors → nalog.gov.ru/opendata/7707329152-massleaders/
disqualified → service.nalog.ru/disqualified.do

Por padrão, a CLI opera em modo --dry-run (analisa e imprime uma amostra); para gravar, é necessário --commit explícito. Os meta-campos <registry>.last_etl, <registry>.last_etl_source, <registry>.last_etl_count são salvos automaticamente — use-os para monitoramento via cron da atualidade dos dados.

Desenvolvimento

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

APIs externas nunca são chamadas diretamente nos testes — apenas via respx (mock de httpx) + fixtures locais em tests/fixtures/.

Limitações

Sem histórico de dirigentes — a Receita Federal não fornece o histórico de trocas via search-API; o histórico completo aparecerá após o carregamento do slice Open Data do EGRUL (planejado para v0.5+).
EFRSB (falência de pessoa jurídica) está fechado para consultas programáticas pela proteção Qrator (403 / verificação "humano ou robô"). Automaticamente, essa verificação frequentemente não é executada; no relatório, isso é um erro de fonte, não "sem falência". Não há solução pronta — é necessário acesso oficial ao Fedresurs ou verificação manual em bankrot.fedresurs.ru.
FSSP na busca pública responde com uma janela de código de imagem. O código não é decifrado: a verificação entra honestamente em errors[] com o motivo captcha_required.
KAD responde a consultas programáticas com 451 (proteção DDoS-Guard). Não é erro de certificado: o site é assinado pela Let's Encrypt. O acesso oficial é com o operador do arquivo. No relatório, isso é "não verificado", não "sem processos".
Se parte das verificações não responder, o nível de risco final é "não determinado" (unknown), não "baixo". Um flags[] vazio por si só não significa "limpo".
Dívidas fiscais são obtidas dos dados abertos da Receita Federal (conjunto "debtam"): os valores de débitos, multas e penalidades estão disponíveis, mas os dados são publicados em snapshot na data de referência, não em tempo real. Confirme o valor atual com o certificado da Receita Federal.
Cadastros locais da Receita Federal (endereços em massa, dirigentes em massa, inabilitados) exigem carregamento regular. Se a exportação estiver vazia ou desatualizada, a verificação responde honestamente "não verificado" e entra em errors[] — "sem correspondências" com base em dados desatualizados não é emitido.
A não apresentação de declarações fiscais não é verificada — não há fonte pública.

O nível Pro (backend hospedado em atomno-mcp-fns-check-server — backend fechado) remove essas limitações por meio de: cache Redis 24h, rotação de proxies para contornar CAPTCHA, snapshot completo do Open Data do EGRUL, verificações em lote de até 100 INN, resumo por IA via LLM. O backend em si não é publicado.

Segurança e status legal

Todas as fontes são dados publicamente abertos da Receita Federal e cadastros relacionados. O uso é legal conforme a Lei Federal 149-FZ "Sobre Informação".
Pessoas jurídicas e empreendedores individuais não se enquadram na Lei Federal 152-FZ (Sobre Dados Pessoais).
Nomes completos de dirigentes pessoas físicas são publicados pela Receita Federal no EGRUL abertamente; nas respostas de saída, o INN da pessoa física dirigente é mascarado (formato XXX*****YY).
Nenhuma operação de escrita em qualquer API externa.
Nenhuma credencial/token é necessária — as fontes são totalmente públicas.

Aviso legal

O serviço é um agregador e interface conveniente sobre dados públicos da Receita Federal. Não é afiliado à Receita Federal da Rússia, EFRSB, KAD, FSSP. Use por sua conta e risco.

As informações nas respostas do serviço não substituem uma avaliação jurídica ou financeira completa. A decisão de celebrar contrato com uma contraparte é sua.

Licença

MIT — consulte LICENSE.