Skip to main content
Glama
wujinkim

korea-business-verify

by wujinkim

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: korea-invoice-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건 사업자 상태 일괄 조회. 경비처리·정산 자동화용.

ParametersJSON Schema
NameRequiredDescriptionDefault
business_numbersYes사업자번호 목록 (최대 100)

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
business_noYes사업자등록번호

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
business_noYes사업자등록번호

TDQS

B3.4/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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 호출 없음.

ParametersJSON Schema
NameRequiredDescriptionDefault
tax_typeNo과세유형 문자열 (생략 시 전체 목록)

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
business_noYes사업자등록번호 (하이픈 무관)
opening_dateYes개업일자 (YYYYMMDD)
representative_nameYes대표자 성명

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 5 tool updatesv0.1.2
    • First observedbatch_check_status
    • First observedcheck_business_status
    • First observedcheck_invoice_eligibility
    • First observedexplain_kr_tax_type
    • First observedverify_business

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

ActivityStale
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • 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
  • A
    license
    A
    quality
    A
    maintenance
    Enables querying Korean procurement corporate profiles and qualifications using business registration numbers through natural language, leveraging the public data API from data.go.kr.
    2
    28
    MIT
  • A
    license
    Not graded
    quality
    D
    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