korean-taxlaw-mcp

한국 세법 자료를 출처별로 통합 조회하기 위한 MCP 서버입니다.

두 출처의 원본을 직접 조회합니다. Python과 FastMCP로 구현했습니다.

• 국세 — 국세청 국세법령정보시스템 (https://taxlaw.nts.go.kr)

• 지방세 — 한국지방세연구원(KILF) 지방세 법령정보시스템 (https://www.olta.re.kr)

• 최신 세법해석례·지방세 유권해석 조회

• 회신·판단·결론 등 상세 본문 구조화

• 문서번호 기반 exact lookup (국세·지방세 각각의 번호 체계 지원)

• 판례·결정례 및 행정 해석기준 검색

• 출처와 근거 유형을 포함한 구조화 응답

기존 korean-law-mcp는 법제처 OPEN API 특성상 국세청 해석례의 목록 검색은 가능하지만 상세 본문 조회에는 제한이 있습니다. korean-taxlaw-mcp의 현재 국세 도메인은 법제처 미러(ntsCgmExpc)를 거치지 않고 국세청 원본을 직접 조회해 문서번호 검색과 상세 본문 조회를 제공합니다.

---

1. 지원 데이터

국세 — 국세청 국세법령정보시스템

영역	대상	검색	문서번호 조회	본문
세법해석례	사전답변, 질의회신(서면질의), 과세기준자문, 고시서면질의	O	O	요지·사실관계·질의내용·회신·관련법령
판례·결정례	과세적부, 이의신청, 심사청구, 심판청구, 판례, 헌재	O	O	처분개요·청구인 주장·처분청 의견·심리 및 판단·결론
행정 해석기준	국세 기본통칙	O	-	조항 본문
행정 해석기준	세법집행기준	O	-	조항명·목차
행정 해석기준	국세청 고시 206건, 훈령 143건	O	-	메타데이터
별표·서식	법령서식 34,487건	O	-	메타데이터·파일 식별자

지방세 — 한국지방세연구원(KILF) 지방세 법령정보시스템

영역	대상	검색	문서번호 조회	본문
유권해석	행정안전부 유권해석(지방세 예규), 법제처 유권해석	O	O	답변요지·질의요지·회신내용·관계법령
판례·결정례	조세심판원 심판결정례, 감사원 심사결정례, 법원 판례, 헌재 결정례	O	O	요지·이유·결정유형

취득세·등록면허세·재산세·자동차세·주민세·지방소득세·지역자원시설세·지방교육세·담배소비세 등 지방세 22개 세목으로 필터할 수 있습니다.

국세와 지방세의 분리

국세와 지방세는 출처·문서번호 체계·권위 수준이 모두 달라 섞지 않고 도메인별로 나눠 둡니다.

	국세	지방세
출처	국세청 국세법령정보시스템	한국지방세연구원 지방세 법령정보시스템
문서번호	서면-2026-법규재산-0119 (종류-연도-분류-일련)	부동산세제과-1794(2026.6.9.)호 (부서-일련)
예규 권위 수준	nts_ruling	local_ruling
도구 접두	search_tax_*, lookup_tax_document	search_local_tax_*, lookup_local_tax_document

응답의 taxLevel 필드로 national·local 을 구분할 수 있습니다.

수록 규모

2026년 8월 실측 기준입니다.

데이터	건수
질의회신	132,638
사전답변	5,117
과세기준자문	1,036
고시서면질의	14
세법해석정비	996
과세적부	518
이의신청	1,478
심사청구	22,233
심판청구	71,349
판례	55,860
헌재	355

지원하지 않는 데이터

데이터	이유
법률·시행령·시행규칙 본문	국가법령정보센터가 원본이며 korean-law-mcp에서 제공
조세조약	법제처 조약 API가 더 안정적이므로 중복 구현하지 않음
일반 판례·헌재 결정 전체	세목이 부여된 조세 사건만 조회
세법집행기준 조항 본문	원본이 연도별 PDF로 배포되어 목차·조항명·PDF 파일 ID까지만 제공
서식 파일 바이너리	POST 폼 다운로드 방식으로 안정적인 GET URL이 없음
감사원 심사청구·납세자보호위원회 심의사례·평가심의사례	별도 모듈·액션으로 현재 미구현
발간책자·세목별요약정보·용어사전·세무일정	법적 근거가 아닌 안내자료로 현재 지원하지 않음

추가 조사 내용은 docs/INVESTIGATION.md를 참고하세요.

---

2. 데이터 출처

세목 구분	출처	주소
국세	국세청 국세법령정보시스템	https://taxlaw.nts.go.kr
지방세	한국지방세연구원(KILF) 지방세 법령정보시스템	https://www.olta.re.kr

두 사이트 모두

• 공개 조회 경로만 사용 (국세청 POST /action.do, 지방세 목록·상세 화면)
• 로그인·CAPTCHA·접근제어 우회 없음
• 별도 세션·쿠키·인증키 불필요
• 모든 응답에 원본 추적 정보 포함

국세:

{
  "sourceAgency": "국세청",
  "sourceSystem": "국세법령정보시스템",
  "sourceId": "200000000000022584",
  "documentNumber": "서면-2026-법규재산-0119",
  "sourceUrl": "https://taxlaw.nts.go.kr/qt/USEQTA002P.do?ntstDcmId=200000000000022584",
  "retrievedAt": "2026-08-19T13:34:58Z"
}

지방세:

{
  "sourceAgency": "행정안전부",
  "sourceSystem": "지방세 법령정보시스템",
  "sourceId": "60099135",
  "documentNumber": "부동산세제과-1794(2026.6.9.)호",
  "sourceUrl": "https://www.olta.re.kr/explainInfo/authoInterpretationDetail.do?num=60099135",
  "retrievedAt": "2026-08-20T04:12:00Z"
}

---

3. 문서번호 검색

문서번호의 표기 차이를 정규화해 동일 문서를 조회합니다.

서면-2026-법규재산-0119
서면 2026 법규재산 0119
서면2026법규재산0119
서면서면-2026-법규재산-0119
질의회신 서면-2026-법규재산-0119
질의회신서면-2026-법규재산-0119
국세청 서면-2026-법규재산-0119

확인된 문서번호 형식은 다음과 같습니다.

형식	구조	예
A	종류-연도-분류-일련	서면-2026-법규재산-0119, 사전-2026-법규소득-0543, 조심-2025-인-4460
B	종류-기관-연도-일련	적부-국세청-2026-0119, 이의-광주청-2026-0024, 심사-부가-2026-0018
C	기관 부서-일련	재정경제부 국제조세협력과-104

A와 B는 두 번째 항목이 4자리 연도인지 여부로 구분합니다.

Exact match 원칙

정확히 일치
→ found: true
→ exactMatch: true
→ document 반환

일치 없음
→ NOT_FOUND
→ similarDocuments 별도 반환

일부만 일치하는 문서는 정답으로 반환하지 않습니다.

lookup_tax_document("법규재산-0119")

→ [NOT_FOUND]

similarDocuments:
  · 서면-2026-법규재산-0119
  · 서면-2015-징세-0119
  · 기준-2023-법규부가-0044
  · 적부-국세청-2020-0119

similarDocuments는 검색 보조 정보이며 요청한 문서로 간주하지 않습니다.

0119와 119처럼 0 패딩만 다른 경우에는 동일한 문서번호로 처리합니다. 정규화는 조회 후보를 확장하기 위한 용도로만 사용하며, 최종 응답에는 국세청 원본의 문서번호를 그대로 반환합니다.

---

4. 키워드 검색

국세법령정보시스템의 실제 검색 결과를 기준으로 검색 문법을 적용합니다.

입력	건수	의미
["상속"]	22,349	단일 키워드
["증여"]	22,924	단일 키워드
["상속","증여"]	14,913	AND
["상속 증여"]	14,913	AND
["상속|증여"]	30,360	OR
["상속"] + 제외 ["증여"]	7,436	NOT

MCP에서는 다음과 같이 사용합니다.

{"query": "상속 공동상속주택"}                  # AND
{"query": "상속 증여", "match": "any"}         # OR
{"query": "상속", "exclude": ["증여"]}         # NOT
{"query": '"공동상속주택 소수지분" 양도'}       # 구절 검색

검색 시 다음 사항에 주의합니다.

• OR 연산자는 ASCII 파이프 |를 사용합니다.
• ¦(U+00A6)는 OR로 동작하지 않습니다.
• 잘못된 정렬 필드를 전달하면 오류가 아니라 0건이 반환됩니다.
• 서버에서는 실측 검증된 DCM_RGT_DTM, FRS_RGT_DTM, SCORE만 사용합니다.

---

5. 가장 쉬운 설치

개발 도구나 Python을 직접 설정하지 않고 Claude Code 또는 Codex에 설치를 맡길 수 있습니다.

1. 사용할 앱 설치

• Claude를 사용한다면 Claude Desktop을 설치하고 로그인합니다.
• Codex를 사용한다면 ChatGPT 데스크톱 앱을 설치하고 로그인한 뒤 Codex를 선택합니다.

2. 설치 요청

둘 중 사용하는 도구에 맞는 내용을 그대로 요청합니다.

Claude Code를 사용하는 경우

korean-taxlaw-mcp를 내 컴퓨터에 설치하고 Claude Desktop에서 사용할 수 있게 설정해줘.
저장소: https://github.com/zisu17/korean-taxlaw-mcp
MCP 이름은 korean-taxlaw로 등록하고, 설치 후 연결 테스트까지 해줘.

Codex를 사용하는 경우

korean-taxlaw-mcp를 내 컴퓨터에 설치하고 Codex에서 사용할 수 있게 MCP로 등록해줘.
저장소: https://github.com/zisu17/korean-taxlaw-mcp
MCP 이름은 korean-taxlaw로 등록하고, 설치 후 목록 확인과 연결 테스트까지 해줘.

Codex에 등록한 MCP 설정은 같은 컴퓨터의 ChatGPT 데스크톱 앱, Codex CLI, IDE 확장에서 공유됩니다. 자세한 내용은 Codex MCP 공식 문서를 참고하세요.

Claude Code 또는 Codex가 명령 실행이나 설정 파일 변경 권한을 요청하면 내용을 확인한 뒤 승인합니다.

3. 앱 재시작

설치가 끝나면 사용 중인 Claude Desktop 또는 ChatGPT 데스크톱 앱을 완전히 종료했다가 다시 실행합니다.

4. 연결 확인

Claude 또는 Codex에서 다음처럼 요청해 봅니다.

국세청에서 "공동상속주택" 관련 세법해석례를 찾아줘.

korean-taxlaw 도구를 사용해 출처 링크와 함께 결과를 반환하면 설치가 완료된 것입니다.

---

6. 직접 설치와 문제 해결

Claude Code나 Codex를 사용할 수 없거나 직접 설치해야 한다면 docs/INSTALLATION.md를 참고하세요. 다음 내용을 포함합니다.

• Windows·macOS·Linux용 uv 설치
• 실행파일 경로와 PATH 확인
• Claude Code 및 Claude Desktop 수동 등록
• 소스 설치와 pip + venv 대체 방법
• HTTP 연결과 문제 해결

---

7. 함께 사용하기

법률·시행령·시행규칙 본문은 korean-law-mcp, 국세청 고유 자료는 korean-taxlaw-mcp로 조회하는 구성을 권장합니다. Claude Code에 두 MCP를 함께 설치해 달라고 요청하거나 Codex에 두 MCP를 함께 등록해 달라고 요청하면 법령 본문과 국세청 해석례·결정례를 출처별로 나누어 확인할 수 있습니다.

---

8. 환경변수

모든 항목은 선택 사항이며 기본값만으로 실행할 수 있습니다.

두 기관의 시스템을 조회하므로 설정도 공통값 + 사이트별 재정의 두 층입니다. 우선순위는 사이트별 > 공통 > 기본값 입니다.

접두	적용 범위
TAXLAW_*	국세·지방세 공통
NTS_*	국세(국세청)만 재정의
OLTA_*	지방세(한국지방세연구원)만 재정의

항목	공통	국세 전용	지방세 전용	기본값
요청 타임아웃(ms)	TAXLAW_TIMEOUT_MS	NTS_TIMEOUT_MS	OLTA_TIMEOUT_MS	20000
재시도 횟수	TAXLAW_RETRIES	NTS_RETRIES	OLTA_RETRIES	3
재시도 대기 base(ms)	TAXLAW_RETRY_BASE_MS	NTS_RETRY_BASE_MS	OLTA_RETRY_BASE_MS	300
분당 요청 한도	TAXLAW_RATE_PER_MIN	NTS_RATE_PER_MIN	OLTA_RATE_PER_MIN	60
버스트 허용량	TAXLAW_RATE_BURST	NTS_RATE_BURST	OLTA_RATE_BURST	20
본문 최대 글자수	TAXLAW_BODY_LIMIT	NTS_BODY_LIMIT	OLTA_BODY_LIMIT	30000
User-Agent	TAXLAW_USER_AGENT	NTS_USER_AGENT	OLTA_USER_AGENT	Chrome UA
캐시 최대 항목 수	TAXLAW_CACHE_MAX	—	—	600

예시:

# 양쪽 다 타임아웃을 10초로
TAXLAW_TIMEOUT_MS=10000

# 공통 10초, 다만 국세청만 30초로 늘림
TAXLAW_TIMEOUT_MS=10000
NTS_TIMEOUT_MS=30000

# 지방세 쪽 요청만 더 천천히
OLTA_RATE_PER_MIN=20

요청 한도는 사이트별로 따로 셉니다. 두 곳이 다른 기관의 서버이므로 한쪽 조회가 다른 쪽 한도를 깎지 않습니다.

캐시는 하나를 공유합니다. 키에 출처를 담아 구분하므로 사이트별 재정의가 없습니다. 이전 이름 NTS_CACHE_MAX 도 계속 동작합니다.

잘못된 값(숫자가 아니거나 하한 미달)은 그 항목만 건너뛰고 다음 후보나 기본값을 씁니다. 설정 오류로 서버가 뜨지 않는 일은 없습니다.

---

9. MCP 도구

총 12개의 도구를 제공합니다.

국세 (국세청)

도구	용도
lookup_tax_document	문서번호 exact lookup
search_tax_interpretations	세법해석례 검색
search_tax_decisions	판례·결정례 검색
get_tax_document	해석례·결정례 본문 조회
search_tax_guidance	기본통칙·집행기준·고시·훈령 검색
get_tax_guidance	통칙·집행기준 특정 조항 조회
search_tax_forms	법령서식·별표 검색
search_taxlaw	국세 전체 영역 통합 검색
tax_research	세무 질의에 대한 층별 근거 수집

지방세 (한국지방세연구원)

도구	용도
search_local_tax_interpretations	지방세 유권해석 검색 (행정안전부·법제처)
search_local_tax_decisions	지방세 심판·판례·감사원·헌재 검색
lookup_local_tax_document	지방세 문서번호 exact lookup + 본문 조회

취득세·재산세 등 지방세 사안은 search_local_tax_* 를, 양도소득세·법인세 등 국세 사안은 search_tax_* 를 사용합니다.

문서번호를 알고 있다면 lookup_tax_document를 먼저 사용합니다.

get_tax_document는 해석례와 결정례의 상세 조회를 하나의 도구로 통합합니다. 국세법령정보시스템의 상세 조회 액션이 문서 유형과 관계없이 동일하기 때문에 별도의 상세 조회 도구로 나누지 않습니다.

사용 예제

문서번호 조회:

{
  "name": "lookup_tax_document",
  "arguments": {
    "document_number": "서면-2026-법규재산-0119"
  }
}

응답 예:

[OK]

found: true
exactMatch: true

서면-2026-법규재산-0119
질의회신 | 양도소득세 | 2026-08-11 | nts_ruling

title:
인구감소지역 내 취득한 분양권이 ’27.1.1.이후 주택으로 전환된 경우 조특법§71의2 적용 여부

relatedLaws:
- 조세특례제한법 제71조의2
- 조세특례제한법 시행령 제68조의2

sections:
- facts
- question
- relatedLawsText

판례·결정례 검색:

{
  "name": "search_tax_decisions",
  "arguments": {
    "query": "공동상속주택",
    "type": "court",
    "result": ["국승"],
    "limit": 3
  }
}

기본통칙 검색:

{
  "name": "search_tax_guidance",
  "arguments": {
    "kind": "basic_ruling",
    "law_name": "상속세 및 증여세법",
    "query": "상속재산"
  }
}

세무 질의 근거 수집:

{
  "name": "tax_research",
  "arguments": {
    "question": "부모가 자녀에게 시가보다 낮은 가격으로 아파트를 양도하면 증여세가 발생하는지"
  }
}

---

10. 법적 근거 구분

세무 자료는 근거의 성격에 따라 구분해 반환합니다.

값	의미
statute	법률
enforcement_decree	시행령
enforcement_rule	시행규칙
nts_ruling	국세청 해석례·예규
nts_guidance	기본통칙·집행기준·고시·훈령
adjudication	과세적부·이의신청·심사청구·심판청구
court_case	법원 판례·헌재 결정

국세청 예규는 과세관청의 법령해석이며 법원을 구속하지 않습니다. 기본통칙과 집행기준은 내부 집행기준으로 법규 자체는 아닙니다.

---

11. 오류 처리

자료가 실제로 존재하지 않는 경우와 원본 서버 문제로 조회하지 못한 경우를 구분합니다.

오류 코드	의미	부존재로 판단 가능
NOT_FOUND	원본에 일치하는 자료가 없음	O
DETAIL_NOT_AVAILABLE	문서는 있으나 원본에서 본문을 제공하지 않음	X
UPSTREAM_ERROR	국세청 오류·점검·비정상 응답	X
PARSE_ERROR	응답 형식이 예상과 다름	X
RATE_LIMITED	서버 자체 요청 한도 초과	X
TIMEOUT	요청 시간 초과	X
INVALID_INPUT	입력 오류	X

오류 응답에는 모델이 확인되지 않은 본문이나 결론을 생성하지 않도록 guardrail 정보를 함께 반환합니다.

HTTP 200 응답이라도 점검 페이지 HTML이 반환되거나 본문이 비정상적으로 비어 있으면 일시 장애로 처리하고 재시도합니다.

---

12. 요청 제한 및 캐시

국세법령정보시스템에 과도한 요청이 발생하지 않도록 호출량을 제한하고 반복 조회를 줄입니다.

요청 제한

• 기본 요청 한도: 분당 60회
• 버스트 허용량: 최대 20회
• tax_research처럼 한 작업에서 여러 요청이 이어지는 경우를 고려해 토큰 버킷 방식 사용

캐시

대상	유지 시간
검색 결과	30분
문서 본문	24시간
통칙·집행기준·고시·훈령	12시간
법령 목록	7일

중복 요청 처리

동일한 요청이 동시에 들어오면 실제 국세법령정보시스템 조회는 한 번만 수행하고 결과를 공유합니다.

HTTP 연결 재사용

httpx의 keep-alive 연결 풀을 사용합니다.

---

13. 면책사항

• 이 서버는 국세청 원문 검색과 구조화를 위한 데이터 접근 계층이며 법률적 판단이나 세무 자문을 제공하지 않습니다.
• 해석례와 결정례는 개별 사안의 사실관계를 기준으로 한 판단입니다.
• 국세청 예규는 과세관청의 법령해석으로 법원을 구속하지 않습니다.
• 기본통칙과 집행기준은 내부 집행기준이며 법규가 아닙니다.
• 개정 법령은 적용시점을 별도로 확인해야 합니다.
• 데이터의 정확성과 최신성은 국세법령정보시스템의 갱신 상태를 따릅니다.
• 법적 효력이 필요한 판단에는 국세법령정보시스템 원문을 확인해야 합니다.
• 실제 신고·불복 등 법적 효력이 있는 행위는 세무사·변호사 등 자격 있는 전문가의 검토가 필요합니다.

---

라이선스

MIT

데이터 출처 고지는 NOTICE를 참고하세요.