atomno-mcp-fns-check

러시아 거래처(법인 및 개인사업자)를 공공 연방세무국(FNS) 데이터(EGRUL/EGRIP, EFRSB, '투명한 비즈니스', FSSP, KAD)를 통해 검증하기 위한 MCP 서버입니다.

Claude Desktop, Cursor, Claude Code, Cline 및 Model Context Protocol(MCP)과 호환되는 모든 클라이언트에 연결할 준비가 되어 있습니다.

목적

AI 에이전트(Claude, Cursor 등)는 일반적으로 러시아 거래처에 대해 알지 못합니다. EGRUL은 검색 엔진에서 제대로 인덱싱되지 않고, FNS의 '투명한 비즈니스' 데이터는 POST 요청과 CAPTCHA 뒤에 숨겨져 있으며, EFRSB는 HTML을 반환합니다. 이 MCP 서버는 에이전트에게 7가지 도구를 제공하여 단 한 번의 호출로 전체 상황을 파악할 수 있게 합니다:

• 기본 정보: 명칭, 주소, OKVED, 대표자.

• 상태: 운영 중, 청산 중, 파산, 청산 완료, 조직 개편.

• 거래 안전성: 대량 주소, 대량 대표자, 자격 박탈, 파산, 세금 체납, 보고서 미제출, 집행 절차, 중재 사건.

주요 도구인 check_contractor(identifier)는 INN 또는 OGRN을 입력받아 판결이 포함된 종합 보고서(safe_to_proceed / manual_review_required / high_risk_do_not_proceed / impossible_contractor_defunct)와 구체적인 권장 사항 목록을 반환합니다.

Related MCP server: mcp-egrul

빠른 시작

설치

pip install atomno-mcp-fns-check

또는 uv / pipx를 통해:

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

작동 확인

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

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

기본적으로 이 패키지는 stdio-MCP 서버로 실행됩니다. 에이전트는 stdin/stdout JSON-RPC를 통해 통신합니다. 셸에서 직접 테스트할 수는 없으며, MCP 클라이언트에 연결해야 합니다. 네트워크 시나리오의 경우 --host/--port와 함께 --transport {http,sse,streamable-http} 플래그를 사용할 수 있습니다.

MCP 클라이언트 연결

Cursor

mcp.json을 편집합니다 (Cursor → Settings → Cursor Settings → MCP):

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

Cursor를 재시작합니다. 채팅에서 "INN 7707083893 거래처를 확인해줘"라고 물어보면 에이전트가 자동으로 check_contractor를 호출합니다.

Claude Desktop

claude_desktop_config.json을 편집합니다 (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

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

Claude Desktop을 재시작합니다.

Claude Code (CLI)

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

Cline (VS Code)

cline_mcp_settings.json에서:

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

도구

사용되는 공공 출처:

• egrul.nalog.ru — EGRUL/EGRIP, 거래처 카드.

• bankrot.fedresurs.ru — EFRSB (연방 파산 정보 등록부).

• pb.nalog.ru — FNS 투명한 비즈니스 (세금 체납, 보고서 미제출).

• fssp.gov.ru — FSSP 집행 절차 데이터베이스.

• kad.arbitr.ru — 중재 사건 카드 인덱스.

• FNS 레지스트리 로컬 슬라이스 — 대량 주소, 대량 대표자, 자격 박탈자 (atomno-mcp-fns-etl 스크립트를 통해 FNS Open Data에서 로드).

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

출처 오류 발생 시 동작

• EGRUL은 유일한 blocking 출처입니다. 사용할 수 없는 경우 check_contractor는 SourceUnavailableError를 발생시킵니다(에이전트는 사람이 읽을 수 있는 메시지를 받습니다).

• 나머지 출처는 best-effort 방식으로 혼합됩니다. FSSP의 CAPTCHA, KAD의 antibot, pb.nalog.ru의 5xx 오류 등은 모두 risks.errors[]에 저장되며 보고서를 실패시키지 않습니다. 상위 수준의 판결은 manual_review_required가 됩니다.

구성

모든 설정은 환경 변수를 통해 이루어집니다. 자격 증명은 필요하지 않습니다(출처는 공개되어 있음).

템플릿은 .env.example을 참조하세요.

FNS 로컬 레지스트리

대량 주소/대표자/자격 박탈자 레지스트리는 FNS Open Data의 CSV/XML 덤프입니다. 패키지에는 내장된 미니 시드(registries_seed.json, 합성 테스트 레코드)가 포함되어 있어 도구가 즉시 작동하고 테스트 INN에서 플래그를 표시할 수 있습니다.

프로덕션 검증을 위해서는 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 출처:

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

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

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

기본적으로 CLI는 --dry-run 모드에서 작동합니다(파싱 및 샘플 출력). 기록을 위해서는 명시적인 --commit이 필요합니다. <registry>.last_etl, <registry>.last_etl_source, <registry>.last_etl_count 메타 필드는 자동으로 저장되므로 데이터 신선도 모니터링(cron)에 사용하세요.

개발

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

테스트에서 외부 API는 절대 직접 호출되지 않으며, respx(httpx 모킹) + tests/fixtures/의 로컬 픽스처를 통해서만 호출됩니다.

제한 사항

• 대표자 이력 없음 — FNS는 검색 API를 통해 변경 이력을 제공하지 않습니다. 전체 이력은 EGRUL Open Data 슬라이드 로드 후 제공될 예정입니다(v0.5+ 계획).

• FSSP / KAD 차단 — 때때로 CAPTCHA / antibot에 의해 차단됩니다. 이 경우 검사는 errors[]로 넘어가고 전체 판결은 manual_review_required가 됩니다.

• 투명한 비즈니스 — 금액 없이 사실 여부('체납 있음' / '보고서 미제출')만 제공합니다. 금액은 IFNS에 직접 문의해야 합니다.

Pro-tier(비공개 백엔드 atomno-mcp-fns-check-server)는 Redis 24시간 캐시, CAPTCHA 우회를 위한 프록시 로테이션, 전체 EGRUL Open Data 슬라이스, 최대 100개 INN 배치 검사, LLM을 통한 AI 요약 등을 통해 이러한 제한을 제거합니다. 백엔드 자체는 공개되지 않았습니다.

보안 및 법적 상태

• 모든 출처는 FNS 및 관련 레지스트리의 공개 데이터입니다. 149-FZ '정보에 관한 법률'에 따라 합법적으로 사용됩니다.

• 법인 및 개인사업자는 152-FZ(개인정보 보호법)의 적용을 받지 않습니다.

• 개인 대표자의 성명은 FNS가 EGRUL에 공개적으로 게시합니다. 아웃바운드 응답에서 대표자의 INN은 마스킹 처리됩니다(XXX*****YY 형식).

• 외부 API에 대한 쓰기 작업은 없습니다.

• 자격 증명/토큰이 필요하지 않습니다. 출처는 완전히 공개되어 있습니다.

면책 조항

이 서비스는 FNS 공개 데이터에 대한 집계 및 편리한 인터페이스입니다. 러시아 연방세무국, EFRSB, KAD, FSSP와 제휴되어 있지 않습니다. 사용자의 책임하에 사용하십시오.

서비스 응답 정보는 완전한 법적 또는 재무적 평가를 대체하지 않습니다. 거래처와의 계약 체결 결정은 사용자가 직접 내려야 합니다.

라이선스

MIT — LICENSE를 참조하세요.

링크

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

• atomno 브랜드의 더 많은 MCP 서버: atomno.ru 카탈로그 (곧 출시)

• MCP 사양: modelcontextprotocol.io