taxlaw-nts-mcp

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

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

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

English

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

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

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

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

제공 도구

국세법령정보시스템 검색·조회

업종코드 ↔ KSIC 매핑 (0.4.0+)

국세청 「업종코드-표준산업분류 연계표」를 빌드 시 JSON으로 변환해 내장. 분류수준 자동 식별로 LLM이 "대분류만 보고 잘못 매칭"하는 실수를 차단합니다.

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

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

전체 메뉴 접근

먼저 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           # 57개 단위 테스트 (선택)
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 Code (Claude Desktop의 MCP 설정)

claude_desktop_config.json 또는 프로젝트별 .mcp.json에 등록:

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

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 ..."

오류 응답 원칙

검색 또는 상세 조회 결과가 없으면 [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