Skip to main content
Glama
Sign In
korea-business-verify

korea-business-verify

by wujinkim
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

korea-business-verify

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

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

도구 5종

도구

설명

verify_business

사업자등록정보 진위확인 (사업자번호·대표자명·개업일자 일치 여부)

check_business_status

휴폐업 상태·과세유형·폐업일자 (호출 빈도 최다)

batch_check_status

최대 100건 일괄 상태조회 (경비처리·정산 자동화)

check_invoice_eligibility

세금계산서 발행 가능 여부 판정 + 근거 (면세/폐업 등)

explain_kr_tax_type

과세유형(일반/간이/면세/비과세) 실무 의미 해설

Related MCP server: korean-public-data-mcp

빠른 시작 — 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": "발급받은_키" }
    }
  }
}
{
  "mcpServers": {
    "korea-business-verify": {
      "command": "node",
      "args": ["/절대경로/korea-business-verify/dist/index.js"],
      "env": { "NTS_SERVICE_KEY": "발급받은_키" }
    }
  }
}

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

  • 서비스키는 사용자 로컬 .env에만 존재합니다. 본 서버는 이를 저장하거나 로그에 남기지 않으며, 국세청 API 인증을 위해서만 사용합니다.

  • 대표자명 등 진위확인 입력값은 요청 즉시 폐기됩니다. 진위확인을 위해 국세청 API로 전송되나, 응답 수신과 함께 어떤 로그·캐시·저장소에도 남기지 않습니다.

  • 캐시되는 것은 사업자번호와 상태조회 결과(24h)뿐입니다. 진위확인은 캐시하지 않습니다.

  • 사업자번호는 국세청 호출 전 체크섬 형식 검증으로 사전 필터링합니다.

신뢰성

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

  • 모든 판정 결과에 basis(근거) 필드 동봉.

개발

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

라이선스

MIT

Available Tools

5 tools
batch_check_statusA

최대 100건 사업자 상태 일괄 조회. 경비처리·정산 자동화용.

Inputs: business_numbers (required).

check_business_statusA

사업자 휴폐업 상태·과세유형·폐업일자 조회. 호출 빈도가 가장 높은 도구.

Inputs: business_no (required).

check_invoice_eligibilityB

과세유형·휴폐업 상태를 종합해 세금계산서 수취 가능 여부 판정 + 근거. 순수 래퍼 대비 차별화 도구.

Inputs: business_no (required).

explain_kr_tax_typeA

한국 과세유형(일반/간이/면세/비과세)의 실무 의미 해설. API 호출 없음.

Inputs: tax_type.

verify_businessA

한국 사업자등록정보 진위확인. 국세청 등록정보와 입력(사업자번호·대표자명·개업일자)의 일치 여부. 대표자명은 검증 즉시 폐기되며 저장되지 않습니다.

Inputs: business_no (required), opening_date (required), representative_name (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 5 tools

    Disambiguation4/5

    The tools are mostly distinct: verify_business checks authenticity, check_business_status and batch_check_status handle single vs bulk status queries, check_invoice_eligibility is a composite assessment, and explain_kr_tax_type is educational. The minor overlap between the two status-check tools is mitigated by clear descriptions.

    Naming Consistency4/5

    Most tools follow a verb_noun pattern (verify_business, check_business_status, explain_kr_tax_type), but 'batch_check_status' deviates slightly with an adjective modifier and 'kr' in one name adds minor inconsistency. Overall the convention is clear and predictable.

    Tool Count5/5

    Five tools is well-scoped for a specialized verification server. Each tool serves a distinct purpose, and the count is neither too thin nor too heavy for the domain.

    Completeness4/5

    The core verification workflow is well covered: authenticity checks, status lookup (single and bulk), invoice eligibility, and tax type explanation. Minor gaps exist, such as a dedicated tool for fetching full business registration details, but the main use cases are supported.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • korea-invoice-mcp

      junter1989k-ai
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to issue, query, and transmit Korean electronic tax invoices (전자세금계산서) via POPBiLL/Linkhub, including VAT computation and NTS reporting.
      MIT

    • korean-public-data-mcp

      SongT-50
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI to query real-time Korean public data including weather, real estate prices, air quality, economic indicators, and business registration via natural language.
      1
      MIT

    • BOIM 보임 — Korean business

      kikiyop1101
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to look up Korean businesses nationwide by region and industry, retrieve public-procurement vendor cards with contract records, and find open public bids from KONEPS, Defense e-Procurement, LH, K-water and Nuri-jangteo. It is read-only and requires no authentication, returning up to five results per tool call on the free tier.
      MIT