홈택스를 Claude에 연결하기 — 국세청 API와 법령 MCP로 세금 조회 자동화

홈택스 세금 신고 내역과 전자세금계산서를 Claude에서 자연어로 조회하고 싶다면, 핵심 질문부터 짚고 가야 합니다. 2026년 8월 기준 국세청이 공식 배포한 홈택스 전용 MCP 서버는 존재하지 않습니다. 대신 공공데이터포털(data.go.kr)의 국세청 공개 API와 법제처 Open API 기반 한국 법령 MCP를 조합하면, 세금 관련 법령 조회와 일부 신고 데이터 확인을 Claude Desktop에서 자동화할 수 있습니다. 이 가이드는 무엇이 가능하고 무엇이 아직 불가능한지를 먼저 구분한 뒤, 실제로 동작하는 설정만 단계별로 다룹니다.

먼저 알아야 할 것 — 가능한 것과 아직 안 되는 것

과장 없이 현재 상태를 정리하면 다음과 같습니다.

하고 싶은 작업	지금 가능한가	방법
세금 관련 법령·조문 실시간 조회	가능	법제처 API 기반 korean-law-mcp
전자세금계산서 발급 의무 기준 등 규정 확인	가능	법령 MCP로 관련 법령 조회
국세청 공개 데이터셋 조회	조건부 가능	data.go.kr API를 직접 MCP 도구로 래핑
본인 홈택스 계정의 신고 내역 자동 로그인 조회	공식 경로 없음	공식 MCP 미출시, 스크래핑은 약관 확인 필요

이 문서는 가장 빠르게 결과를 얻을 수 있는 법제처 법령 MCP 연결을 중심으로 설명하고, 국세청 공개 API 래핑은 확장 경로로 안내합니다. 홈택스 웹을 직접 자동화하는 스크래핑 방식은 서비스 이용약관과 법적 리스크를 반드시 먼저 검토하세요.

동작 구조

사용자 (Claude Desktop)
       │
       ▼
  Claude AI 모델
       │  MCP 프로토콜
       ▼
  MCP 서버 (로컬 실행)
       │  HTTP/REST
       ▼
법제처 Open API / 국세청 공개 API
       │
       ▼
  법령·신고·조회 데이터

MCP(Model Context Protocol)는 AI가 외부 도구와 실시간으로 데이터를 주고받는 표준 프로토콜입니다. MCP 서버는 사용자 기기에서 로컬로 실행되며, Claude가 도구를 호출하면 서버가 외부 API를 대신 호출해 결과를 돌려줍니다.

준비물

• Node.js 18 이상 (npx 실행에 필수)
• Claude Desktop 최신 버전
• 법제처 Open API 키 (한국 법령 MCP 사용 시 필수)
• 공공데이터포털(data.go.kr) 계정 및 일반 인증키 (국세청 공개 API 활용 시)
• 터미널 (macOS: 기본 터미널, Windows: PowerShell)

1단계 — API 키 발급

세금 법령 조회가 목적이라면 법제처 키만 있어도 시작할 수 있습니다.

법제처 Open API 키 (한국 법령 MCP용 · 필수)

1. open.law.go.kr/LSO/openApi/guideList.do 에 접속합니다.
2. 회원가입 후 “API 활용 신청”을 클릭합니다.
3. 필요한 API(법령 검색, 조문 조회, 판례 검색 등)를 선택해 신청합니다.
4. 발급된 키를 저장합니다. 활성화까지 최대 1 영업일이 걸릴 수 있습니다.

공공데이터포털 API 키 (국세청 공개 API용 · 선택)

1. data.go.kr 에 접속해 회원가입합니다.
2. “국세청”으로 검색해 필요한 데이터셋을 찾습니다.
3. 활용신청 후 승인되면 일반 인증키가 발급됩니다.

키를 복사할 때 앞뒤 공백이 섞이지 않도록 주의하세요. 인증 실패의 흔한 원인입니다.

2단계 — MCP 서버 선택

세금 관련 법령 조회에 바로 쓸 수 있는 한국 법령·계약 MCP 서버는 다음과 같습니다.

서버	저장소	설치 방법	API 키
한국 법령 MCP	github.com/chrisryugj/korean-law-mcp	npx	필요
한국 법령 MCP 서버	github.com/SeoNaRu/korean-law-mcp	stdio (직접 빌드)	필요
한국 계약서 자동생성 MCP	github.com/kimlawtech/korean-contracts	stdio (직접 빌드)	불필요

가장 먼저 시도할 서버는 chrisryugj/korean-law-mcp입니다. 법제처 Open API 42개를 17개 MCP 도구로 래핑한 서버로, npx 방식이라 별도 빌드 없이 실행됩니다. 세금 법령 조회는 물론, AI가 인용한 조문이 실제로 존재하는지 검증하는 verify_citations 도구도 포함합니다.

3단계 — MCP 서버 설치

터미널에서 setup 명령을 한 번 실행합니다.

npx korean-law-mcp setup

이 명령은 Node.js 18 이상 환경에서만 정상 동작합니다. 실행 전 node -v로 버전을 확인하세요.

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

Claude Desktop 설정 파일 위치는 운영체제마다 다릅니다.

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

파일을 열고 mcpServers 항목을 추가합니다.

{
  "mcpServers": {
    "korean-law-mcp": {
      "command": "npx",
      "args": ["korean-law-mcp"],
      "env": {
        "LAW_API_KEY": "여기에_발급받은_법제처_API_키_입력"
      }
    }
  }
}

LAW_API_KEY 값에 1단계에서 발급받은 법제처 키를 넣습니다. 따옴표와 쉼표 등 JSON 문법을 꼼꼼히 확인하세요. 문법 오류가 있으면 Claude Desktop 자체가 실행되지 않습니다.

5단계 — 재시작 및 연결 확인

설정을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 실행합니다. 창을 닫는 것만으로는 재시작되지 않을 수 있으니, macOS는 메뉴바, Windows는 시스템 트레이에서 완전히 종료하세요.

다시 실행하면 채팅 입력창 근처에 MCP 도구 아이콘이 표시됩니다. 아이콘을 클릭해 korean-law-mcp 항목과 도구 목록이 보이면 연결에 성공한 것입니다.

6단계 — 세금 관련 프롬프트 실행

연결이 끝나면 다음과 같이 요청해 봅니다.

부가가치세 신고 기한과 관련 법령을 알려줘.

전자세금계산서 발급 의무 기준을 법령에서 찾아줘.

법령 MCP가 정상 연결됐다면 Claude가 도구를 호출해 법제처 API에서 실시간으로 조회한 결과를 보여줍니다. 응답 하단에 출처 법령이 표시되면 제대로 동작하는 것입니다.

흔한 오류와 해결 방법

”MCP server not found” / npx 실행 오류

npx korean-law-mcp setup은 Node.js 18 미만에서 실패합니다. node -v로 버전을 확인하고, 18 미만이면 Node.js 공식 사이트에서 최신 LTS를 설치하세요.

API 키 인증 실패

환경변수 이름은 서버마다 다를 수 있습니다. 반드시 해당 서버의 GitHub README에서 정확한 환경변수 이름을 확인하세요. 또한 키를 붙여넣을 때 앞뒤 공백이 들어가지 않았는지 점검합니다. 오타나 공백 하나로 인증이 실패합니다.

JSON 파싱 오류로 Claude Desktop이 실행되지 않음

claude_desktop_config.json에 JSON 문법 오류가 있으면 Claude Desktop 자체가 뜨지 않습니다. jsonlint.com 같은 검증 도구에 파일 내용을 붙여넣어 오류 위치를 찾으세요.

Windows에서 npx 명령을 찾지 못하는 경우

command를 "npx" 대신 "npx.cmd"로 바꿔 보세요. Windows에서는 .cmd 확장자를 명시해야 하는 경우가 있습니다.

{
  "mcpServers": {
    "korean-law-mcp": {
      "command": "npx.cmd",
      "args": ["korean-law-mcp"],
      "env": {
        "LAW_API_KEY": "여기에_발급받은_법제처_API_키_입력"
      }
    }
  }
}

국세청 공개 API로 확장하기

법령 조회를 넘어 실제 데이터를 다루려면 공공데이터포털의 국세청 공개 API를 직접 MCP 도구로 래핑하는 방법이 있습니다. 다만 다음 점을 고려하세요.

• 인증 방식이 구현 난이도를 좌우합니다. 단순 조회 API는 일반 인증키만으로 호출되지만, 전자세금계산서처럼 사업자 인증이 필요한 API는 공인인증서·간편인증 처리가 추가돼 복잡도가 올라갑니다.
• 민감 정보는 프롬프트에 직접 넣지 마세요. MCP 서버는 로컬에서 돌지만 Claude Desktop은 입력 내용을 Anthropic 서버로 전송합니다. 납세자 번호나 세금 원본 데이터는 프롬프트에 붙여넣지 말고, API가 서버 측에서 직접 처리하도록 도구를 설계하는 것이 안전합니다.

관련 MCP 서버 더 살펴보기

세금·법률 업무를 AI로 확장하려면 법률·세금 카테고리에서 더 많은 서버를 찾아보세요.

• 한국 법령 MCP — 법제처 42개 API를 17개 MCP 도구로 래핑. 세금 법령 실시간 조회와 verify_citations 인용 검증을 지원합니다.
• 한국 법령 MCP 서버 — 국가법령정보센터 API로 법령·판례·행정규칙을 검색합니다.
• 한국 계약서 자동생성 MCP — 사업자용 9종 계약서를 Claude Code에서 자동 생성합니다. 세금계산서 발행에 앞선 계약 단계에서 활용할 수 있습니다.

MCP 서버 전체 목록은 /servers, 다른 가이드는 /guides에서 확인하세요.

자주 묻는 질문

홈택스와 Claude를 직접 연결하는 공식 MCP 서버가 있나요?

2026년 8월 현재 국세청이 공식 배포한 홈택스 전용 MCP 서버는 확인되지 않습니다. 다만 공공데이터포털(data.go.kr)에 국세청 관련 공개 API가 있어, 이를 래핑하면 일부 기능을 AI에 연결할 수 있습니다. 공식 배포 전까지는 법령 MCP 서버와 공공 API를 조합하는 방식이 현실적입니다.

전자세금계산서 조회를 AI로 자동화할 수 있나요?

전자세금계산서 관련 API는 사업자 인증을 거친 후 사용할 수 있습니다. 공공데이터포털에 등록된 API를 MCP 도구로 래핑하면 Claude에서 자연어로 조회할 수 있지만, 인증 방식(공인인증서·간편인증)에 따라 구현 복잡도가 크게 달라집니다.

API 키는 어디서 발급받나요?

법제처 API는 open.law.go.kr에서, 국세청 공개 API는 data.go.kr에서 신청합니다. 각 포털에서 회원가입 후 원하는 API를 검색해 활용신청하면 됩니다. 법제처 키는 활성화까지 최대 1 영업일이 걸릴 수 있습니다.

Claude Desktop 외에 Cursor나 VS Code에서도 사용할 수 있나요?

네, MCP를 지원하는 클라이언트라면 동일하게 사용할 수 있습니다. Cursor는 설정 파일 위치가 다르지만 JSON 구조는 같습니다. VS Code는 Cline 등 MCP 호환 확장을 설치하면 같은 방식으로 연결됩니다.

Claude가 도구를 인식하지 못할 때는 어떻게 하나요?

JSON 문법 오류, 환경변수 누락, 명령어 경로 오류가 주요 원인입니다. Claude Desktop의 개발자 도구 콘솔이나 로그 파일에서 오류 메시지를 먼저 확인하세요. npx 명령은 Node.js 18 이상에서만 동작합니다.

개인정보나 납세 정보가 외부로 유출될 위험은 없나요?

MCP 서버는 사용자 기기에서 로컬로 실행되므로 데이터는 기본적으로 기기 안에서 처리됩니다. 다만 Claude Desktop은 입력 내용을 Anthropic 서버로 전송하므로, 납세자 번호나 세금 원본 데이터는 프롬프트에 직접 붙여넣지 마세요. 민감 정보는 API가 서버 측에서 직접 처리하도록 MCP 도구를 설계하는 것이 안전합니다.

다음 단계

먼저 법제처 API 기반 korean-law-mcp로 세금 법령을 조회하며 MCP 연결을 익히세요. 이후 공공데이터포털에서 국세청 공개 API를 발굴해 직접 MCP 도구를 개발하거나 기존 서버에 기여하는 방식으로 기능을 넓힐 수 있습니다.

새로운 홈택스 전용 MCP 서버를 발견하거나 직접 개발했다면 MCP모아에 등록해 한국 AI 개발자 커뮤니티와 공유해 주세요.