Korea Business Verify

io.github.wujinkimPublished by GitHub account wujinkimv0.1.1Updated Oct 24, 2026

한국 사업자 검증 액션 MCP 서버 — 진위확인·휴폐업·과세유형·세금계산서 발행 가능 여부 (국세청 공공데이터 기반)

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

A local MCP server that lets an assistant verify Korean business registration details, check business status and tax type, and judge tax-invoice eligibility via

What you can do
Verify a Korean business registration by matching business number, representative name and opening date against National Tax Service data. Check whether a business is active or closed, its tax type and closure date. Batch-check the status of up to 100 business numbers at once. Judge whether a tax invoice can be issued and return the stated basis. Explain what general, simplified, exempt and non-taxable tax types mean in practice.
When to use it
Useful when an assistant handles Korean vendor onboarding, expense or settlement checks, or invoice preparation and needs to confirm a business number is real and still trading. Also handy for bulk screening of supplier lists.
Requirements
Runs locally via npx or a built Node.js package. Live mode needs a National Tax Service service key from the public data portal, supplied as the NTS_SERVICE_KEY environment variable; the key must be requested separately for the verification and status services. Without a key it runs in demo mode with fictitious business numbers. Network access to the National Tax Service API is required.
Before you install
The service key is a credential and should stay in the local environment file. Representative names and other verification inputs are sent to the National Tax Service API, so avoid submitting personal data you are not permitted to share. Status results are cached for 24 hours. Results are reference only, not tax advice, and have no legal effect; official proof must come from Hometax documents. The manifest declares a differently named key variable than the README, so confirm which name the build

Installation

In SourceWeft

  1. Open Korea Business Verify in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

korea-business-verify

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

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

도구 5종

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

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

bash
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 권장):

json
{  "mcpServers": {    "korea-business-verify": {      "command": "npx",      "args": ["-y", "korea-business-verify"],      "env": { "NTS_SERVICE_KEY": "발급받은_키" }    }  }}
대안: 로컬 빌드 경로로 연동
json
{  "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(근거) 필드 동봉.

개발

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

라이선스

MIT

Source: README.md at commit 27cef29

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts