사업자등록번호 조회 MCP — 국세청 API를 Claude에서 바로 검증하기

Q: uvx 명령어를 쓰려면 무엇을 설치해야 하나요?

uvx는 Python 패키지 관리 도구 uv에 포함된 실행 명령입니다. 터미널에서 'curl -LsSf https://astral.sh/uv/install.sh | sh' 명령으로 uv를 먼저 설치하면 uvx도 함께 사용할 수 있습니다.

Q: Claude Code(CLI)에서도 같은 방법으로 연결할 수 있나요?

네. Claude Code는 프로젝트 루트의 .claude/settings.json 또는 ~/.claude/settings.json에 MCP 서버를 등록합니다. 설정 구조는 Claude Desktop과 동일하므로 mcpServers 블록을 그대로 옮겨 사용하면 됩니다.

Q: Windows 환경에서는 설정 파일 경로가 다른가요?

네. Windows에서는 Claude Desktop 설정 파일이 %APPDATA%\Claude\claude_desktop_config.json 경로에 있습니다. 파일 탐색기 주소창에 해당 경로를 직접 입력하면 열 수 있습니다.

국세청 사업자등록 진위확인 API를 MCP(Model Context Protocol)로 Claude에 연결하면, 사업자등록번호를 Claude 채팅창에 입력하는 것만으로 실시간 진위확인과 상태 조회가 가능합니다. 별도 코드 작성 없이 공공데이터포털 MCP 서버 모음의 uvx 명령 하나로 설치가 끝나며, Claude Desktop 설정 파일에 서버 정보를 추가하면 바로 사용할 수 있습니다. 이 가이드는 API 키 발급부터 Claude 연결, 실제 조회 테스트까지 막힘 없이 안내합니다.

왜 사업자등록번호 조회 MCP가 필요한가

거래처 계약이나 세금계산서 발행 전에 사업자등록번호의 유효성을 확인하는 일은 업무에서 자주 발생합니다. 국세청 홈텍스나 공공데이터포털 API를 직접 호출하는 방법도 있지만, 매번 브라우저를 열거나 별도 스크립트를 실행하는 것은 번거롭습니다.

MCP를 이용하면 Claude가 직접 국세청 API를 호출하는 도구(tool)를 사용할 수 있게 됩니다. 자연어로 “이 사업자 폐업했어?”라고 물으면 Claude가 API를 호출하고 결과를 해석해서 답해 줍니다. AI 워크플로우 안에 한국 공공데이터를 끌어들이는 가장 빠른 방법입니다.

Claude Desktop / Claude Code
        │  자연어 요청
        ▼
  MCP 클라이언트 (내장)
        │  tool_call
        ▼
data-go-mcp-servers (로컬 프로세스)
        │  HTTP 요청 + API 키
        ▼
국세청 사업자등록 진위확인 API (data.go.kr)
        │  JSON 응답
        ▼
  MCP 클라이언트 → Claude → 한국어 해석 결과

사전 준비물

항목	필요 여부	비고
Claude Desktop (최신 버전)	필수	claude.ai/download
Python 3.10 이상	필수	uv 설치에 필요
uv (Python 패키지 관리자)	필수	uvx 명령 포함
공공데이터포털 계정	필수	data.go.kr 무료 가입
국세청 사업자등록 API 키	필수	신청 후 발급 (대부분 즉시 승인)

단계별 설치 및 설정 방법

1단계: 공공데이터포털 API 키 발급

data.go.kr에 접속해 회원가입 또는 로그인합니다.
검색창에 “국세청_사업자등록정보 진위확인 및 상태조회 서비스” 를 입력하고 해당 API를 찾습니다.
[활용신청] 버튼을 클릭하고 활용 목적을 간단히 작성한 뒤 신청합니다.
마이페이지 → 오픈API → 개발계정 목록에서 발급된 일반 인증키(Decoding) 를 복사해 안전한 곳에 보관합니다.

API 키는 %2B, %2F 등 URL 인코딩된 형태(Encoding)가 아니라 Decoding(평문) 키를 사용해야 합니다.

2단계: uv 설치

uv가 이미 설치되어 있다면 이 단계를 건너뛰세요.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 터미널을 재시작하거나 source ~/.bashrc (또는 ~/.zshrc)를 실행해 환경 변수를 적용합니다.

3단계: data-go-mcp-servers 동작 확인

공공데이터포털 MCP 서버 모음은 uvx로 바로 실행할 수 있습니다. Claude Desktop에 등록하기 전에 터미널에서 한 번 실행해 패키지가 정상적으로 다운로드되는지 확인합니다.

uvx data-go-mcp.nps-business-enrollment@latest --help

오류 없이 도움말이 출력되면 준비 완료입니다.

4단계: Claude Desktop 설정 파일 수정

Claude Desktop 설정 파일을 열어 MCP 서버를 등록합니다.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

파일이 없으면 새로 만들면 됩니다. 아래 형식을 참고하세요.

{
  "mcpServers": {
    "data-go-nts-business": {
      "command": "uvx",
      "args": ["data-go-mcp.nps-business-enrollment@latest"],
      "env": {
        "DATA_GO_KR_API_KEY": "여기에_발급받은_Decoding_API_키_입력"
      }
    }
  }
}

이미 다른 MCP 서버가 등록되어 있다면 mcpServers 객체 안에 "data-go-nts-business" 블록을 추가하면 됩니다.

보안 주의: API 키가 담긴 이 파일은 버전 관리(git)에 포함하지 않도록 .gitignore에 추가하거나 별도로 관리하세요.

5단계: Claude Desktop 재시작 및 연결 확인

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 실행합니다.

새 대화를 시작하면 입력창 하단 또는 도구 아이콘 영역에 MCP 도구가 표시됩니다.
도구 목록에 nts-business 관련 항목이 보이면 연결 성공입니다.

연결이 안 된다면 다음을 확인하세요.

증상	원인	해결 방법
MCP 도구가 보이지 않음	설정 파일 JSON 문법 오류	jsonlint 등으로 검증
API 오류 (401/403)	API 키 오타 또는 Encoding 키 사용	Decoding 키 재확인
uvx 명령 없음	uv 미설치 또는 경로 문제	`which uvx` 로 경로 확인 후 재설치
패키지 다운로드 실패	네트워크 또는 PyPI 접근 불가	VPN 또는 프록시 환경 확인

6단계: 사업자등록번호 조회 테스트

Claude Desktop에서 새 대화를 열고 아래처럼 자연어로 요청해 보세요.

사업자등록번호 123-45-67890의 현재 상태를 조회해 줘.

또는 진위확인이 필요할 때:

사업자등록번호 000-00-00000, 대표자 홍길동, 개업일 2020-01-01로 진위확인 해줘.

Claude는 MCP 도구를 호출해 국세청 API 응답을 받은 뒤, 계속사업자 / 휴업 / 폐업 여부와 함께 한국어로 결과를 해석해 답변합니다.

흔한 오류와 해결 방법

”SERVICE_KEY_IS_NOT_REGISTERED_ERROR” 응답

API 키가 유효하지 않거나 아직 승인되지 않은 상태입니다. 공공데이터포털 마이페이지에서 신청 현황을 확인하고, Encoding 키 대신 Decoding 키를 사용했는지 재확인하세요.

”LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR” 응답

일일 트래픽 한도(기본 1,000건)를 초과했습니다. 공공데이터포털에서 트래픽 증량을 신청하거나 다음 날 다시 시도하세요.

Claude가 “도구를 찾을 수 없다”고 응답

MCP 서버가 연결되지 않은 상태입니다. Claude Desktop 재시작 후에도 동일하면, 설정 파일 경로와 JSON 문법을 다시 점검하세요.

활용 시나리오

사업자등록번호 조회 MCP는 단순 진위확인을 넘어 다양한 업무에 응용할 수 있습니다.

계약서 검토 자동화: 계약서에서 사업자번호를 추출해 즉시 진위확인
거래처 관리: 신규 거래처 등록 전 폐업 여부 자동 체크
세금계산서 오류 예방: 발행 전 수신처 사업자 상태 사전 확인
스프레드시트 정리: 사업자 목록을 붙여넣어 일괄 상태 조회

함께 쓰면 좋은 한국 공공데이터 MCP

사업자 정보 조회와 함께 아래 MCP 서버를 활용하면 업무 자동화의 범위를 크게 넓힐 수 있습니다.

한국 부동산 MCP — 국토교통부 실거래가 조회로 거래처 사업장 시세 파악
공공데이터포털 MCP 서버 모음 — 국민연금·조달청·금감원 등 다양한 공공 API 통합
공공데이터 카테고리 전체 보기 — 한국 공공데이터를 활용하는 MCP 서버 목록

더 많은 한국 MCP 서버는 MCP모아 서버 목록에서 확인하세요.

자주 묻는 질문

공공데이터포털 API 키 발급에 얼마나 걸리나요?

국세청 사업자등록 진위확인 API는 신청 즉시 자동 승인되는 경우가 많습니다. 다만 기관 검토가 필요한 경우 최대 2~3 영업일이 소요될 수 있으니 공공데이터포털 마이페이지에서 승인 상태를 확인하세요.

uvx 명령어를 쓰려면 무엇을 설치해야 하나요?

uvx는 Python 패키지 관리 도구 uv에 포함된 실행 명령입니다. 터미널에서 curl -LsSf https://astral.sh/uv/install.sh | sh 명령으로 uv를 먼저 설치하면 uvx도 함께 사용할 수 있습니다.

사업자등록번호 진위확인과 사업자 상태 조회는 다른가요?

진위확인은 입력한 사업자등록번호·대표자명·개업일자가 국세청 DB와 일치하는지 확인합니다. 상태 조회는 해당 사업자가 현재 계속사업자인지, 휴업 또는 폐업 상태인지를 알려줍니다. 두 가지 모두 MCP를 통해 Claude에서 조회할 수 있습니다.

Claude Code(CLI)에서도 같은 방법으로 연결할 수 있나요?

네. Claude Code는 프로젝트 루트의 .claude/settings.json 또는 ~/.claude/settings.json에 MCP 서버를 등록합니다. 설정 구조는 Claude Desktop과 동일하므로 mcpServers 블록을 그대로 옮겨 사용하면 됩니다.

하루 API 호출 한도는 어떻게 되나요?

공공데이터포털의 국세청 사업자등록 진위확인 API는 기본적으로 일 1,000건 트래픽을 제공합니다. 대량 조회가 필요하다면 공공데이터포털 마이페이지에서 트래픽 증량을 신청할 수 있습니다.

Windows 환경에서는 설정 파일 경로가 다른가요?

네. Windows에서는 Claude Desktop 설정 파일이 %APPDATA%\Claude\claude_desktop_config.json 경로에 있습니다. 파일 탐색기 주소창에 해당 경로를 직접 입력하면 열 수 있습니다.

다음 단계

이 가이드로 국세청 사업자등록번호 조회 MCP를 Claude에 성공적으로 연결했다면, 같은 방식으로 다른 한국 공공데이터 API도 연결할 수 있습니다. 공공데이터포털 MCP 서버 모음은 국민연금·조달청·금융감독원 등의 API도 포함하고 있으니, 업무 환경에 맞게 추가로 활용해 보세요. 직접 만든 MCP 서버가 있다면 MCP모아에 등록해 더 많은 분들과 공유할 수도 있습니다.