taxlaw-nts-mcp

국세법령정보시스템(https://taxlaw.nts.go.kr) 자료를 MCP 도구로 검색하는 STDIO 서버입니다.

법제처에서 바로 찾기 어려운 국세청 세법해석, 질의회신, 조세 불복 문서, 기본통칙, 별표/서식, 발간책자, 홈택스 상담사례를 보완 검색합니다.

전용 고수준 도구가 아직 없는 메뉴도 접근할 수 있도록, 확인된 사이트 메뉴/action 목록 조회와 action.do 원시 호출, 같은 사이트 HTML 텍스트 조회 도구를 함께 제공합니다.

English

무엇에 쓰나

세법 검토의 근거는 법 조문만이 아니라 국세청 해석례·질의회신·기본통칙, 조세심판례, 홈택스 상담사례인 경우가 많습니다. 이 자료들은 법제처 국가법령정보센터에서는 잘 나오지 않고 국세법령정보시스템에만 있습니다. 이 서버는 그 자료를 찾아 본문까지 가져오고, 세법 검토에서 자주 문제되는 부분을 함께 처리합니다.

• 국세청 전용 자료 조회 — 세법해석례·질의회신·기본통칙·조세심판례·홈택스 상담사례·발간책자를 번호나 키워드로 찾아 본문을 가져옵니다.

• 인용 번호 실존 확인 — 답변에 들어갈 해석례·심판례 번호가 실제 DB에 있는지 대조합니다(verify_nts_citations). 없는 번호는 걸러 내거나 "공개DB 미발견"으로만 남겨, 존재하지 않는 예규를 근거로 다는 일을 막습니다.

• 적용 시점 확인 — 귀속연도를 지정하면 그 해에 적용되던 조문으로 검토하고(build_application_timetable), 개정으로 사문화됐거나 폐지·대체된 해석인지 판정합니다(assess_doctrine_validity). 신·구 조문은 나란히 대조할 수 있습니다(diff_article_versions).

• 계산식 조문 원문 유지 — 조특법 고용증대·통합고용 세액공제처럼 표·산식이 든 조문은 일반 법령 API에서 산식이 빠지기도 하는데, 여기서는 산식까지 그대로 가져옵니다.

• 업종코드 감면 판정 — 창업중소기업·중소기업특별세액감면 검토에서 해당 업종코드가 감면 대상인지 표준산업분류와 대조해 해당/제외/범위밖/애매로 판정합니다(classify_industry_for_article).

• 정리된 형식으로 회신 — 결론 → 케이스별 표 → 근거 법령(출처별·원문링크) → 미검증 보충(⚠) 순으로 정리돼, 의견서·검토 메모에 옮기기 쉽습니다.

법 조문·판례 원문은 법제처 MCP(korean-law-mcp), 국세청 해석·통칙·심판례는 이 서버에서 확인하는 식으로 나눠 씁니다. API 키나 비용은 없으며, 최종 판단은 원문과 전문가 확인을 거쳐야 합니다.

Related MCP server: Korean Law ALIO MCP

korean-law-mcp와 함께 쓰는 방식

세법 질의는 먼저 korean-law-mcp로 법령 조문, 시행령, 판례, 조세심판 등 법제처/법령 DB 자료를 확인하고, 법제처 검색에서 국세청 질의회신·기본통칙·홈택스 상담사례·발간책자를 찾지 못할 때 이 서버로 보완 조회하는 흐름을 권장합니다.

두 MCP가 같은 판례·결정례·해석례를 찾으면 문서번호/청구번호/사건번호에서 공백·하이픈을 제거한 값, 생산일자/의결일자, 제목을 기준으로 하나로 정리하세요. 같은 항목은 중복 나열하지 말고 양쪽 출처 ID를 함께 남기며, 국세법령정보시스템에만 있는 원문 스니펫·홈택스 상담·기본통칙·발간책자는 이 서버 결과로 보완합니다.

이 서버는 국세법령정보시스템 응답에 존재한 항목만 표시하며, 검색 실패나 외부 사이트 오류가 나면 [NOT_FOUND], [EXTERNAL_API_ERROR], [INVALID_PARAMETER] 같은 마커와 추측 금지 경고를 반환합니다.

응답 포맷 — 5단 구조 (0.6.0+)

MCP InitializeResult.instructions로 LLM에 자동 주입됩니다. 클라이언트(Claude Code 등)는 이를 system-reminder로 노출하여 LLM이 아래 5단 구조를 따르도록 강제합니다. 단순 1~2문장 단답형 질문은 생략 가능.

1. 결론 (요지) — 사용자 이해와 어긋나면 맨 앞에서 명시. 핵심 판정·조치 1~2문장.

2. 매트릭스 (케이스별 처리) — 분기 기준(소득구성·신고유형·거래유형 등)을 표로 정리. 각 행에 결론 + 근거 법령 함께 표기.

3. 법령 래퍼 (Citation) — 출처별로 분리:

   • (1) 법률 — korean-law-mcp.get_law_text 결과

   • (2) 시행령/시행규칙 — MST·시행일 명시

   • (3) 기본통칙 — list/get_taxlaw_basic_ruling 또는 본문 인용

   • (4) 국세청 해석례 / 심판례 / 판례 — 문서번호·일자·핵심 인용문

4. AI 보충 해석 (⚠ 검증되지 않음) — LLM 자체 지식·실무 팁은 별도 단락에 ⚠ 경고와 함께 분리.

5. 인용/피드백 prompt 2줄 — "인용 본문을 더 부착해드릴까요?" + "1~5점 + 한 줄 코멘트".

출처 격리 — (1)~(4)는 검증된 출처. 섹션 내용을 다른 섹션과 섞지 말 것. AI 보충과의 혼합 금지.

연도 검증 의무 — 해석례 인용 시 get_taxlaw_document_text(targetYear=YYYY)로 인용 법조문 시점 자동 검증. 구법조문 기반 예규는 ⚠ 사문화 가능성 경고 동봉.

사문화 자동 채점 (0.7.0+) — 예규/심판례/판례를 인용할 때 assess_doctrine_validity(id, targetYear)를 호출하면 8단계 분류(valid_current / target_or_later / before_target / partially_outdated / repealed_or_superseded / no_citations / no_target / uncertain)와 6단계 최종 판정(valid_current / needs_current_check / partially_outdated / likely_outdated / superseded_or_repealed / unverified)을 자동 채점하고, korean-law-mcp로 현행 조문 대조 + 후속 결정(대법원·헌재) 확인까지 이어지는 next-action 큐를 반환합니다.

제공 도구

tools/list에 바로 노출되는 도구와, 세션 고정 토큰 절감을 위해 call_taxlaw_extra(name, args) 게이트웨이로 호출하는 저빈도 도구로 나뉩니다. 저빈도 도구도 TAXLAW_EXPOSE_ALL=1 환경변수를 주면 모두 직접 노출됩니다.

검색·본문 조회

조문 시점·적용시기 (법제처 DRF 보완)

국세법령정보시스템에 없는 부칙·시점본·조문 신구대조를 법제처 국가법령정보 Open API로 보완합니다. 귀속연도가 걸린 질문은 여기부터 시작합니다.

세액감면 업종 판정

call_taxlaw_extra로 호출하는 저빈도 도구

call_taxlaw_extra({ name, args }) 형태로 호출합니다.

• 업종코드 ↔ KSIC 매핑 — lookup_upjong_code · lookup_ksic_code · lookup_ksic_prefix · search_industry_by_keyword · resolve_industry_class · classify_industry_for_article · upjong_db_info

• 발간책자·홈택스·사이트 메뉴 — get_taxlaw_hometax_counsel_text · search_taxlaw_publications · list_taxlaw_publication_categories · list_taxlaw_site_menus · get_taxlaw_page_text · call_taxlaw_action

• 하위호환 별칭 — search_taxlaw_interpretations(=search_taxlaw_documents) · get_taxlaw_interpretation_text(=get_taxlaw_document_text)

업종코드 ↔ KSIC 매핑 DB

국세청 「업종코드-표준산업분류 연계표」를 빌드 시 JSON으로 내장(약 1.5MB, 1,784 레코드, 귀속연도 2024). 분류수준(대/중/소/세/세세)을 자동 식별해 LLM이 "대분류만 보고 잘못 매칭"하는 실수를 차단합니다.

예 — 조특법 시행령 §27③ 16호 판정(749942 vs 852000):

call_taxlaw_extra({
  name: "classify_industry_for_article",
  args: {
    industryName: "기타 전문, 과학 및 기술 서비스업",
    upjongCode:   "749942",     // 국세청 중분류 74 "전문 서비스업"
    excludeNames: ["수의업"]
  }
})
// → verdict: out_of_scope (16호가 가리키는 KSIC 중분류 73과 불일치)

전체 메뉴 접근

이 절의 list_taxlaw_site_menus·call_taxlaw_action·get_taxlaw_page_text는 저빈도 도구라 기본적으로 call_taxlaw_extra로 감싸 호출합니다(TAXLAW_EXPOSE_ALL=1이면 직접 호출 가능). 먼저 list_taxlaw_site_menus로 메뉴 키, URL, 확인된 actionId, 기본 paramData를 확인합니다. 전용 도구가 있는 메뉴는 해당 고수준 도구를 쓰고, 없는 메뉴는 call_taxlaw_action에 actionId, defaultParamData, refererPath를 넘겨 원시 응답을 조회합니다. 세목별요약정보·세법개정건의처럼 정적 HTML로 제공되는 자료는 get_taxlaw_page_text에 /html/U_0101.html, /cm/USECMJ001M.do 같은 경로를 넘겨 조회합니다. 세무일정은 list_taxlaw_site_menus(query="세무일정")에서 확인한 ASECMC001MR01 action에 year, month를 넘겨 조회할 수 있습니다.

빠른 시작

git clone https://github.com/kim-go-chon/taxlaw-nts-mcp.git
cd taxlaw-nts-mcp
npm install
npm run build      # tsc + 내장 DB(JSON) 복사
npm test           # 240개 단위 테스트 (선택)
npm start          # MCP STDIO 서버 실행

설치 후 추가 다운로드 없이 모든 도구가 즉시 동작합니다. 업종코드↔KSIC 매핑 DB(src/data/upjong-ksic.json, 약 1.5MB, 1,784 레코드, 귀속연도 2024)는 저장소에 포함되어 있습니다.

매핑 DB를 최신 데이터로 교체하려면 (선택)

국세청이 「업종코드-표준산업분류 연계표」를 갱신했을 때만 필요합니다. 본인이 받은 최신 CSV를 환경변수로 지정해 재빌드하면 됩니다.

# Linux/macOS
UPJONG_CSV=/path/to/업종코드-표준산업분류\ 연계표.csv npm run build:data

# Windows PowerShell
$env:UPJONG_CSV = "C:\path\to\업종코드-표준산업분류 연계표.csv"
npm run build:data

# 그 다음 (두 OS 공통)
npm run build

설치 — MCP 클라이언트별 안내

Claude Desktop / Claude Code (STDIO 직접 지원)

claude_desktop_config.json(Claude Desktop) 또는 프로젝트별 .mcp.json(Claude Code)에 등록:

{
  "mcpServers": {
    "taxlaw-nts": {
      "command": "node",
      "args": ["/absolute/path/to/taxlaw-nts-mcp/build/index.js"]
    }
  }
}

Claude.ai 웹 (브라우저)

현재 본 MCP는 claude.ai 웹에서 직접 사용할 수 없습니다. claude.ai의 Custom Connectors 기능은 공인 인터넷으로 노출된 원격 MCP 서버(HTTPS)만 지원하지만, 본 서버는 STDIO 전용입니다.

권장 대안 — Claude Desktop: 위 "Claude Code" 섹션의 claude_desktop_config.json 등록 방식이 그대로 적용됩니다. Claude Desktop은 macOS/Windows 앱에서 로컬 STDIO MCP를 직접 지원하므로 별도 배포 없이 즉시 동작합니다. claude.ai 웹과 동일한 모델·대화 히스토리를 사용하면서 본 MCP를 쓰려면 Claude Desktop이 가장 간단한 경로입니다.

Codex (OpenAI Codex CLI)

~/.codex/config.toml에 등록:

[mcp_servers.taxlaw-nts]
command = "node"
args = ["/absolute/path/to/taxlaw-nts-mcp/build/index.js"]
default_tools_approval_mode = "approve"

Windows 사용자는 백슬래시 경로 + node.exe 절대경로 권장:

[mcp_servers.taxlaw-nts]
command = 'C:\Program Files\nodejs\node.exe'
args = ['C:\Users\사용자명\.codex\mcp\taxlaw-nts-mcp\build\index.js']
default_tools_approval_mode = "approve"

업데이트 절차 (양쪽 공통)

cd /path/to/taxlaw-nts-mcp
git pull
npm install
npm run build      # CSV가 등록되어 있으면 데이터도 함께 재빌드

MCP 클라이언트(Claude Code, Codex)를 재시작하면 새 버전이 활성화됩니다.

npm 전역 설치 (선택)

npm 레지스트리에 배포된 경우 더 짧게 등록 가능합니다.

npm install -g taxlaw-nts-mcp

{ "mcpServers": { "taxlaw-nts": { "command": "taxlaw-nts-mcp" } } }

[mcp_servers.taxlaw-nts]
command = "taxlaw-nts-mcp"

환경 변수

API 키는 필요하지 않습니다. 기본 User-Agent는 taxlaw-nts-mcp/<version> (+https://github.com/kim-go-chon/taxlaw-nts-mcp)로 클라이언트 식별이 가능하게 설정되어 있습니다. 국세법령정보시스템에서 봇으로 차단되는 경우에 한해 일반 브라우저 UA로 덮어쓰세요.

TAXLAW_USER_AGENT="Mozilla/5.0 ..."

도구 콜 1건에 시간예산을 걸 수 있습니다(tail-latency 방어, 소진 시 부분 결과 + 재호출 안내).

TAXLAW_TOOL_BUDGET_MS=90000   # 도구 콜 시간예산(ms). 기본 90000, 0=무제한

오류 응답 원칙

검색 또는 상세 조회 결과가 없으면 [NOT_FOUND]와 isError: true를 반환합니다. 외부 사이트 오류는 [EXTERNAL_API_ERROR], 잘못된 입력은 [INVALID_PARAMETER]로 반환합니다. 결과 본문에는 출처 URL과 실제 조회한 ID를 함께 표시합니다.

개발

npm run build
npm run watch
npm test
npm pack --dry-run

데이터 출처 · 저작권 안내

• 국세법령정보시스템 응답: 본 MCP가 실시간 호출로 받아오는 모든 본문은 국세법령정보시스템(https://taxlaw.nts.go.kr)의 공개 자료입니다. 저작권은 각 발행기관(국세청·법원·헌법재판소·기재부 등)에 있습니다.

• 업종코드↔KSIC 매핑 DB: 본 저장소는 「업종코드-표준산업분류 연계표」(국세청 홈택스 공개 자료)를 JSON으로 변환한 결과(src/data/upjong-ksic.json, 귀속연도 2024)를 포함합니다. 사용자가 추가로 다운로드할 필요 없이 즉시 사용 가능합니다. 최신 데이터로 교체하려면 본인이 받은 CSV를 UPJONG_CSV 환경변수로 지정해 npm run build:data && npm run build를 다시 실행하세요.

• 인용 시: "출처: 국세청 「업종코드-표준산업분류 연계표」" 형태로 출처를 함께 표기하세요.

이용약관·법적 고지

이 도구는 국세법령정보시스템(https://taxlaw.nts.go.kr)의 공개 자료를 개인 학습·연구·법률 업무 보조 목적으로 조회하기 위한 비공식 클라이언트입니다. 이 프로젝트는 국세청과 무관하며, 사용자가 직접 NTS의 이용약관과 법령을 준수할 책임이 있습니다.

• 준수 사항

  • NTS 사이트의 이용약관 및 robots.txt를 사용 전 확인하세요.

  • 본 MCP는 기본 User-Agent로 클라이언트 식별 문자열을 보냅니다. 식별 정보를 제거하거나 위장할 목적으로 변경하지 마세요.

  • NTS 서버에 부담을 주지 않도록 대량 일괄 수집(scraping), 짧은 간격의 반복 호출은 피하세요. 발간책자 enrichment는 동시 8건으로 제한되어 있습니다.

  • 조회한 자료를 무단 재배포·상업적 가공하지 마세요. 법령·판례·해석례의 저작권은 각 기관에 있습니다.

• 한계

  • 결과는 NTS 응답 시점의 데이터입니다. 법적 효력 있는 판단은 반드시 원문(법제처/국세청)과 변호사·세무사·관할 기관 확인이 필요합니다.

  • LLM이 결과를 추측·생성하지 않도록 가드 메시지를 함께 반환하지만, 최종 판단은 사용자에게 있습니다.

• 면책

  • 본 도구의 사용으로 발생한 법률·세무 판단 오류, NTS 약관 위반, 차단 조치, 데이터 손실 등에 대해 저자/기여자는 책임지지 않습니다(MIT License 참조).

라이선스

MIT