korea-business-verify
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@korea-business-verifyCheck business status for 123-45-67890"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
korea-business-verify
한국 사업자 검증 MCP 서버 — 진위확인·휴폐업·과세유형·세금계산서 발행 가능 여부를 AI 에이전트에게 도구로 제공합니다. 국세청 공공데이터포털 API 기반.
⚠️ 면책: 국세청 공공데이터 기준의 참고 결과이며 세무 자문이 아닙니다. 법적 효력이 있는 증명은 홈택스 발급 문서를 참조하세요.
도구 5종
도구 | 설명 |
| 사업자등록정보 진위확인 (사업자번호·대표자명·개업일자 일치 여부) |
| 휴폐업 상태·과세유형·폐업일자 (호출 빈도 최다) |
| 최대 100건 일괄 상태조회 (경비처리·정산 자동화) |
| 세금계산서 발행 가능 여부 판정 + 근거 (면세/폐업 등) |
| 과세유형(일반/간이/면세/비과세) 실무 의미 해설 |
Related MCP server: korea-invoice-mcp
빠른 시작 — DEMO (서비스키 불필요)
npx -y korea-business-verify # 서비스키 없으면 자동 DEMO 모드 (가상 사업자번호로 5종 도구 체험)소스 빌드(개발자용):
npm install && npm run build && DEMO_MODE=1 node dist/index.js
DEMO 가상 사업자번호 (체크섬은 유효하나 실제 존재하지 않는 번호):
번호 | 상태 | 과세유형 |
| 계속사업자 | 일반과세자 → 세금계산서 가능 |
| 계속사업자 | 면세사업자 → 계산서 대상 |
| 폐업자 | → 발행 불가 |
라이브 모드 (실제 국세청 API)
서비스키 발급: docs/get-api-key.md (진위·상태 두 서비스 각각 신청 필요)
.env파일:NTS_SERVICE_KEY=발급받은_서비스키실행:
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 toolsbatch_check_statusA
최대 100건 사업자 상태 일괄 조회. 경비처리·정산 자동화용.
| Name | Required | Description | Default |
|---|---|---|---|
| business_numbers | Yes | 사업자번호 목록 (최대 100) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description relies on the verb '조회' (lookup) to imply a read-only operation and states the batch limit of up to 100. It does not disclose return format, error behavior, or operational requirements, leaving some gaps for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core function and use case without unnecessary detail. It is appropriately concise for a simple lookup tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single required parameter and absence of an output schema, the description provides sufficient context: it states the batch limit and purpose. It does not elaborate on response content, but for a straightforward lookup tool this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers the parameter fully ('사업자번호 목록 (최대 100)'), so baseline is 3. The tool description adds minimal parameter-specific meaning beyond confirming the batch use case, matching the array structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies '사업자 상태 일괄 조회' (batch lookup of business status) with a max of 100, clearly stating the verb, resource, and batch scope. It distinguishes from siblings like 'check_business_status' by emphasizing batch capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the intended use case ('경비처리·정산 자동화용' – for expense processing and settlement automation), providing context. However, it does not explicitly mention alternatives or when not to use it, though the batch nature implies it's for bulk queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_business_statusA
사업자 휴폐업 상태·과세유형·폐업일자 조회. 호출 빈도가 가장 높은 도구.
| Name | Required | Description | Default |
|---|---|---|---|
| business_no | Yes | 사업자등록번호 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It does state that the operation is a read-only '조회' and lists the returned fields (status, tax type, closure date). However, it omits permission requirements, rate limits, and behavior for active or not-found businesses, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, front-loaded sentences. The first conveys the core function and outputs, and the second offers a lightweight usage-frequency signal. No filler or redundancy exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one well-documented parameter and no output schema, the description covers the essential purpose and expected return fields. It falls short only in not explicitly addressing sibling-tool selection or edge-case behavior, but the tool is simple enough that the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter business_no is already described as '사업자등록번호'. The description adds no additional format, validation, or usage detail beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('조회' / query) and clearly names the resource and scope: business closure status, tax type, and closure date. This distinguishes it from siblings like batch_check_status and check_invoice_eligibility by specifying exactly what it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage-related hint is '호출 빈도가 가장 높은 도구' (most frequently called tool), which is not actionable guidance. It does not explain when to use this tool versus batch_check_status, check_invoice_eligibility, or verify_business, and no exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_invoice_eligibilityB
과세유형·휴폐업 상태를 종합해 세금계산서 수취 가능 여부 판정 + 근거. 순수 래퍼 대비 차별화 도구.
| Name | Required | Description | Default |
|---|---|---|---|
| business_no | Yes | 사업자등록번호 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral disclosure. It conveys that the tool synthesizes multiple factors (tax type, closure status) and outputs a determination with reasoning, but it does not address permissions, error behavior, or whether the operation is read-only, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the core function in the first sentence. The second sentence about being a differentiation tool is somewhat unnecessary but not verbose, so the overall structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema. The description explains the core logic and mentions providing a rationale, which is helpful, but it does not specify the exact return structure or errors. Given the absence of annotations and output schema, this is moderately complete but not fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single parameter business_no as '사업자등록번호' (business registration number), so schema coverage is 100%. The description adds no extra parameter nuance, matching the baseline score for fully covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool evaluates tax type and business closure status to determine eligibility for receiving tax invoices, and provides the rationale. It distinguishes itself by noting it is '순수 래퍼 대비 차별화 도구', implying a more integrated analysis than a simple wrapper, which sets it apart from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus the sibling tools. The phrase about being a 'differentiation tool' relative to a pure wrapper is vague and does not mention alternatives, scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
explain_kr_tax_typeA
한국 과세유형(일반/간이/면세/비과세)의 실무 의미 해설. API 호출 없음.
| Name | Required | Description | Default |
|---|---|---|---|
| tax_type | No | 과세유형 문자열 (생략 시 전체 목록) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that no API call is made, signaling a side-effect-free, static explanation. It also specifies the scope of tax types covered, which adds useful context beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two efficient sentences, opening with the core purpose and immediately adding the key behavioral note about no API calls. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple informational tool with one optional parameter and no output schema, the description is largely adequate. It covers the purpose and a key behavioral trait, but it does not indicate the output format or explicitly mention that omitting the parameter returns the full list (though the schema does). Given the low complexity, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the parameter simply as '과세유형 문자열', but the description enriches it by enumerating the valid tax type values (일반/간이/면세/비과세). This additional context helps the agent understand what values to pass, exceeding the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: explaining the practical meaning of Korean tax types, listing the specific categories (일반/간이/면세/비과세). It uses a specific verb ('explain') and resource, and it is distinctly different from sibling tools that perform checks and verifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'API 호출 없음' (no API call) provides clear context that this is an informational reference tool rather than a data-fetching operation, implying it should be used for conceptual understanding. However, it does not explicitly name alternatives or state when not to use it, so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
verify_businessA
한국 사업자등록정보 진위확인. 국세청 등록정보와 입력(사업자번호·대표자명·개업일자)의 일치 여부. 대표자명은 검증 즉시 폐기되며 저장되지 않습니다.
| Name | Required | Description | Default |
|---|---|---|---|
| business_no | Yes | 사업자등록번호 (하이픈 무관) | |
| opening_date | Yes | 개업일자 (YYYYMMDD) | |
| representative_name | Yes | 대표자 성명 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the representative name is immediately discarded and not stored, which is a meaningful privacy behavior. However, it does not explicitly state whether the operation is read-only, if it triggers external calls, or if there are any side effects, leaving gaps in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core purpose. Every sentence adds value: the first defines the function, the second provides a key privacy detail. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three required parameters and no output schema, the description explains the verification logic and data handling but does not describe the return value or result format. It mentions '일치 여부' (match status) implicitly but does not specify whether the result is a boolean, status object, or something else, leaving a completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing full details for all three parameters (business_no, opening_date, representative_name). The description lists the same fields without adding new format or semantic details beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool verifies Korean business registration info by checking if input (business number, representative name, opening date) matches National Tax Service records. It distinctly identifies the resource and action, and the mention of matching against tax data differentiates it from sibling tools like check_business_status or batch_check_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for authenticating business registration details but does not explicitly state when to prefer this over siblings or any exclusions. It lacks guidance on when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.2- First observed
batch_check_status - First observed
check_business_status - First observed
check_invoice_eligibility - First observed
explain_kr_tax_type - First observed
verify_business
TDQS
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Korean fact-verification tools for AI agents: business registration, address, DART, apt prices, laws
Validate EU, UK, AU VAT numbers for AI agents. EU ViDA e-invoicing compliance.
Verify Korean business registration numbers (National Tax Service) — KYB for Korean counterparties …
Korean business registry, corporate info, parcel tracking, validation APIs
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides AI agents with Korean national fiscal data (budgets, settlements, and fiscal programs) from multiple government APIs through 7 tools, enabling natural language queries.31-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to issue, query, and transmit Korean electronic tax invoices (전자세금계산서) via POPBiLL/Linkhub, including VAT computation and NTS reporting.MIT

io.github.opendataofficial
AlicenseAqualityAmaintenanceEnables querying Korean procurement corporate profiles and qualifications using business registration numbers through natural language, leveraging the public data API from data.go.kr.228MIT- AlicenseNot gradedqualityDmaintenanceEnables AI to query real-time Korean public data including weather, real estate prices, air quality, economic indicators, and business registration via natural language.1MIT