korea-business-verify

한국 사업자 검증 MCP 서버 — 진위확인·휴폐업·과세유형·세금계산서 발행 가능 여부를 AI 에이전트에게 도구로 제공합니다. 국세청 공공데이터포털 API 기반.

⚠️ 면책: 국세청 공공데이터 기준의 참고 결과이며 세무 자문이 아닙니다. 법적 효력이 있는 증명은 홈택스 발급 문서를 참조하세요.

도구 5종

도구	설명
verify_business	사업자등록정보 진위확인 (사업자번호·대표자명·개업일자 일치 여부)
check_business_status	휴폐업 상태·과세유형·폐업일자 (호출 빈도 최다)
batch_check_status	최대 100건 일괄 상태조회 (경비처리·정산 자동화)
check_invoice_eligibility	세금계산서 발행 가능 여부 판정 + 근거 (면세/폐업 등)
explain_kr_tax_type	과세유형(일반/간이/면세/비과세) 실무 의미 해설

빠른 시작 — DEMO (서비스키 불필요)

npx -y korea-business-verify   # 서비스키 없으면 자동 DEMO 모드 (가상 사업자번호로 5종 도구 체험)

소스 빌드(개발자용): npm install && npm run build && DEMO_MODE=1 node dist/index.js

DEMO 가상 사업자번호 (체크섬은 유효하나 실제 존재하지 않는 번호):

번호	상태	과세유형
1111111119	계속사업자	일반과세자 → 세금계산서 가능
2222222227	계속사업자	면세사업자 → 계산서 대상
3333333336	폐업자	→ 발행 불가

라이브 모드 (실제 국세청 API)

1. 서비스키 발급: docs/get-api-key.md (진위·상태 두 서비스 각각 신청 필요)
2. .env 파일:

   NTS_SERVICE_KEY=발급받은_서비스키
   

3. 실행: node dist/index.js (키가 있으면 자동으로 라이브 모드)

Claude Desktop / Cursor 연동

claude_desktop_config.json (npx 권장):

{
  "mcpServers": {
    "korea-business-verify": {
      "command": "npx",
      "args": ["-y", "korea-business-verify"],
      "env": { "NTS_SERVICE_KEY": "발급받은_키" }
    }
  }
}

<details><summary>대안: 로컬 빌드 경로로 연동</summary>

{
  "mcpServers": {
    "korea-business-verify": {
      "command": "node",
      "args": ["/절대경로/korea-business-verify/dist/index.js"],
      "env": { "NTS_SERVICE_KEY": "발급받은_키" }
    }
  }
}

</details>

개인정보 보호 (무저장 원칙)

• 서비스키는 사용자 로컬 .env에만 존재합니다. 본 서버는 이를 저장하거나 로그에 남기지 않으며, 국세청 API 인증을 위해서만 사용합니다.
• 대표자명 등 진위확인 입력값은 요청 즉시 폐기됩니다. 진위확인을 위해 국세청 API로 전송되나, 응답 수신과 함께 어떤 로그·캐시·저장소에도 남기지 않습니다.
• 캐시되는 것은 사업자번호와 상태조회 결과(24h)뿐입니다. 진위확인은 캐시하지 않습니다.
• 사업자번호는 국세청 호출 전 체크섬 형식 검증으로 사전 필터링합니다.

신뢰성

• API 장애(5xx·타임아웃·네트워크) 시 자동 재시도(지수 백오프, 3회). 인증/형식 에러는 즉시 명확한 에러 코드로 응답.
• 모든 판정 결과에 basis(근거) 필드 동봉.

개발

npm run build     # tsc
npm test          # vitest (커버리지 96%)
npm run lint      # eslint

라이선스

MIT