nts-tax-mcp

국세법령정보시스템(taxlaw.nts.go.kr) + 지방세법령정보시스템(olta.re.kr) 통합검색을 Claude에서 바로 쓸 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.

국세: 사전답변 · 서면질의 · 질의회신(국세청/기획재정부/법제처), 조세심판원 심판청구, 국세청 심사청구, 법원 판례, 법령

지방세 (v3에서 추가): 취득세 · 재산세 · 자동차세 · 지방소득세 · 등록면허세 관련 조세심판원 결정례, 감사원 심사결정례, 헌법재판소 결정례, 법원판례, 법제처/행정안전부 유권해석, 자치단체 질의회신

법령정보 확장 (v5, 확장판 server_ext.py에서 추가): 국가법령정보센터(law.go.kr) Open API 기반으로 대법원·하급심 판례, 법령 연혁·특정 시점 조문, 법령해석례, 행정규칙 (기본통칙 등), 조세조약, 자치법규(조례)까지 커넥터 하나로 검색

v5 — 서버컴퓨터 이전 + 법제처(law.go.kr) 도구 8개 추가 (2026-08)

Railway 크레딧 소진으로 서버가 죽어(2026-08-08) 자체 서버컴퓨터 상시 구동 + Tailscale Funnel 노출 방식으로 이전했습니다 (2026-08-09 완료). 이전 작업 중 법제처(law.go.kr) Open API 도구 8개를 추가로 붙여서 커넥터 하나로 총 14개 도구를 쓸 수 있게 확장했습니다.

• 확장 진입점: server_ext.py — 기존 server.py의 도구 6개(국세/지방세)를 from server import mcp로 그대로 물려받고, law_go_kr.py 클라이언트를 통해 법제처 도구 8개를 추가로 등록합니다. server.py 자체는 수정되지 않았으므로, 기존 6개 도구만 필요하면 server.py를 그대로 실행해도 됩니다.

• 새 도구 8개: court_case_search/court_case_detail(법제처 판례), law_interpretation_search(법령해석례), law_history_search(법령 연혁 시행본 목록), law_article_as_of(특정 날짜 시행 조문 원문 — 예규·판례 인용 당시 조문 확인용), admin_rule_search(행정규칙 — 기본통칙·조사사무처리규정·고시), treaty_search(조세조약 원문·발효일), ordinance_search(자치법규 — 지방세 감면조례 등)

• 전제조건: law.go.kr Open API는 등록된 IP에서만 동작합니다. open.law.go.kr → OpenAPI 신청내역에서 서버의 공인 IP를 사전 등록해야 합니다. 미등록 상태면 법제처 8개 도구만 "인증 실패"가 뜨고 기존 국세/지방세 6개 도구는 정상 동작합니다. 환경변수 LAW_API_OC(law.go.kr 가입 시 발급받는 기관코드, 필수)로 인증 계정을 지정합니다. 개인 식별정보라 이 저장소에는 실제 값을 커밋하지 않고, 서버컴퓨터에만 두는 .gitignore된 로컬 파일에서 불러옵니다.

• 현재 운영 방식: 서버컴퓨터에서 run_server.bat(포트 8734, server_ext.py 실행)를 Windows 작업 스케줄러(nts-tax-mcp, 부팅 시 SYSTEM 권한 자동 실행)로 상시 구동하고, tailscale funnel --bg 8734로 고정 주소 https://desktop-ika1349.tail81ecba.ts.net/mcp 에 외부 노출합니다. 최초 설치는 setup.ps1(GitHub에서 소스 다운로드 → 의존성 설치 → 작업 스케줄러 등록까지 자동화) 1회 실행으로 끝납니다.

Related MCP server: LexGuard MCP

v5.1 — 조문 파싱 버그 수정 + 조문 잘림 명시 (2026-08-16)

• 절 첫 조문 파싱 버그 수정: law_article_as_of가 절(節)·관·장이 시작되는 조문 (예: 소득세법 104조·55조)을 조회하면 조문 본문 대신 "제6절 …" 같은 표제만 반환하던 버그를 수정했습니다. 표제 노드가 실제 조문과 같은 <조문번호>를 단 채 먼저 나오는 구조가 원인으로, 조번호 문자열이 본문에 없는 표제 블록을 걸러냅니다.

• 조문 잘림 명시 + max_chars 노출: 조문이 max_chars(기본 6000자)를 넘으면 이전에는 뒷부분(마지막 항들)이 아무 표시 없이 잘렸습니다. 이제 잘린 경우 응답에 "잘림" 항목으로 전체 길이와 재조회 방법을 안내하고, law_article_as_of 도구에 max_chars 파라미터를 추가해 전문을 받을 수 있습니다.

• 운영 주의 — .bat은 반드시 CRLF 줄바꿈: run_server.bat이 LF 줄바꿈으로 저장되면 cmd.exe가 줄을 건너뛰어 PORT=8734 설정이 무시되고 서버가 기본 포트 8000으로 뜹니다(실제 장애 사례 — Funnel이 8734를 바라보므로 커넥터가 먹통이 됨). 편집기에 따라 저장 시 줄바꿈이 LF로 바뀔 수 있으니 .bat 수정 후에는 CRLF인지 확인하세요.

v5.2 — 행정규칙 조문 단위 조회 (2026-08-17)

admin_rule_search에 article(조번호)·max_chars·start_char 파라미터를 추가했습니다. 외국환거래규정(재정경제부 고시, 약 30만 자) 같은 대형 고시는 전문 반환이 불가능해 이전에는 앞 10,000자만 보고 끝이었는데, 이제 조번호를 지정하면 해당 조문만 잘라 받습니다 — 예: 해외직접투자 신고는 serial=외국환거래규정 일련번호, article="9-5" (제9-5조). 조번호를 모르면 start_char 오프셋으로 이어 읽을 수 있고, 잘린 경우 응답의 "잘림" 항목이 다음 조회 방법을 안내합니다.

속도 개선(2026-08-18): law.go.kr 응답을 10분 캐싱해 같은 법령의 조문을 연속 조회할 때 법 전체 XML(소득세법 61만 자 등)을 다시 받지 않습니다(두 번째 조문부터 즉시 반환). 연혁 조회의 페이지 크기 파라미터 오류(numOfRows→display)도 고쳐 HTTP 왕복을 5회→1회로 줄였습니다 (조문 1건 콜드 조회 1.1초→0.6초 실측).

v3 — 지방세법령정보시스템(olta.re.kr) 추가

국세와 지방세는 조세심판원 사건번호 체계 자체가 다릅니다.

• 국세: 조심-YYYY-지역청코드-NNNN (예: 조심-2023-서-9465)

• 지방세: 조심YYYY지NNNN (예: 조심2026지0284)

실제로 두 시스템에서 같은 키워드로 검색해본 결과, 조세심판원 결정례는 거의 겹치지 않습니다 (국세청 시스템은 지방세 사건을 색인하지 않음). 그래도 안전하게 nts_and_olta_precedent_search 도구는 문서번호 정규화 후 중복을 제거하고 duplicates_removed 건수를 함께 알려줍니다.

파일 구성

nts-tax-mcp/
├── server.py                    # MCP 서버 본체 (FastMCP) — 기본 도구 6개 (국세+지방세)
├── server_ext.py                # 확장 진입점 — server.py 6개 + 법제처 8개 = 14개 도구
├── nts_tax_ruling_search.py     # 국세: taxlaw.nts.go.kr 검색 클라이언트
├── olta_tax_ruling_search.py    # 지방세: olta.re.kr 검색 클라이언트
├── law_go_kr.py                 # 법령정보: law.go.kr Open API 클라이언트 (판례/법령/해석례/행정규칙/조약/자치법규)
├── test_mcp_client.py           # 서버 상태 독립 점검 스크립트
├── client/                      # MCP 커넥터 우회 독립 클라이언트 (CLI 포함)
│   ├── nts_client.py
│   ├── nts_search.py
│   └── README.md
├── requirements.txt
├── Procfile                     # Railway 배포용 (레거시 — 현재 운영은 서버컴퓨터+Tailscale Funnel)
├── setup.ps1                    # 서버컴퓨터 최초 설치 스크립트 (소스 다운로드→의존성→작업 스케줄러 등록)
├── run_server.bat               # 확장판(server_ext.py) 상시 구동용 — 작업 스케줄러가 부팅 시 실행
└── local_env.bat                # (커밋 안 됨) LAW_API_OC 등 개인 식별정보 — .gitignore 처리, 서버컴퓨터에서 직접 생성

제공 도구

server.py는 기본 6개, server_ext.py는 기본 6개 + 법제처 8개 = 총 14개 도구를 노출합니다. 실제 운영 서버(서버컴퓨터)는 server_ext.py로 구동되어 14개 도구가 모두 열려 있습니다.

기본 6개 (국세·지방세, server.py)

확장 8개 (법제처 law.go.kr, server_ext.py에서만 추가)

v4 — 심층 검색 기능 (개선 후보 전면 반영)

• OLTA 페이지네이션·기간·정렬: olta_collection_search로 특정 카테고리를 10건 단위로 깊게 탐색. 기간(YYYYMMDD)과 최신순 정렬은 서버측에서 처리되어 정확합니다.

• OLTA 본문 조회: olta_get_detail로 조세심판원·헌재 결정문 전문(결정요지·처분개요·판단) 을 가져옵니다.

• NTS 서버측 세목필터: tax_type_filter에 정확한 세목명(양도소득세, 법인세, 부가가치세, 상속증여세, 종합부동산세 등 14종)을 주면 서버측 코드 필터가 자동 적용되어, 전체 데이터 기준으로 정확하게 걸러집니다.

세부 데이터 사양·코드표는 DATA_SOURCES.md 참고.

v2.1 버그 수정 (중요)

client/ 폴더 작업 중 발견된 문제를 수정했습니다.

• 날짜 필터(date_from/date_to)가 검색 자체를 깨뜨리던 문제 — taxlaw.nts.go.kr 통합검색 화면에는 애초에 기간 필터 UI가 없어서, 이전 버전에서 추측으로 넣었던 bltnStrtDtm/bltnEndDtm 서버 파라미터가 잘못된 값으로 취급되어 검색 결과가 통째로 0건으로 나오는 문제가 있었습니다. 이번에 해당 파라미터를 제거하고, 결과를 받아온 뒤 date 필드로 걸러내는 클라이언트단 필터로 교체했습니다.

• 문서번호(doc_no) 필드에 검색어 하이라이트 마커(<!HS>, <!HE>)가 안 지워져 nts_ruling_get_by_doc_no의 정확 매칭이 실패하던 문제도 함께 수정했습니다.

MCP 커넥터 우회 독립 클라이언트 (client/)

Claude 커넥터 연결이 불안정할 때, MCP를 거치지 않고 서버에 직접 접속해서 검색할 수 있는 독립 클라이언트를 client/ 폴더에 추가했습니다. 사용법은 client/README.md 참고.

cd client
python nts_search.py --ping
python nts_search.py "조정대상지역" -c precedent -n 10

v2 개선사항

최초 버전 이후 아래 항목들을 개선했습니다.

1. 로컬 실행 확인

pip install -r requirements.txt
python server.py

기본적으로 http://0.0.0.0:8000/mcp 에서 streamable-http 방식으로 서비스됩니다. 포트는 환경변수 PORT로 바꿀 수 있습니다.

PORT=8765 python server.py

환경변수 옵션

2. 배포

2-A. 현재 운영 방식 — 서버컴퓨터 상시 구동 + Tailscale Funnel (2026-08~)

Railway 크레딧 소진으로 서버가 다운된 뒤(2026-08-08), 자체 서버컴퓨터에서 상시 구동하는 방식으로 전환했습니다. 14개 도구(server_ext.py)가 이 방식으로 운영됩니다.

1. 서버컴퓨터 관리자 PowerShell에서 setup.ps1 1회 실행 — GitHub에서 소스를 받아 의존성을 설치하고, Windows 작업 스케줄러에 nts-tax-mcp(부팅 시 SYSTEM 권한 자동 실행)를 등록한 뒤 즉시 기동합니다.

   Set-ExecutionPolicy -Scope Process Bypass -Force
   .\setup.ps1

2. run_server.bat이 PORT=8734를 설정하고 server_ext.py를 실행합니다 (로그: server.log). LAW_API_OC는 이 파일에 직접 적지 않고, .gitignore된 로컬 파일 (local_env.bat — set LAW_API_OC=본인_기관코드 한 줄)에서 불러옵니다. 이 파일이 없으면 법제처 8개 도구만 동작하지 않고 기본 6개는 정상입니다.

3. Tailscale을 설치해 로그인 후 Funnel로 외부에 고정 주소로 노출합니다.

   tailscale funnel --bg 8734

4. 실제 MCP 서버 URL(고정): https://desktop-ika1349.tail81ecba.ts.net/mcp

포트를 바꾸면 run_server.bat의 PORT와 tailscale funnel의 대상 포트를 함께 바꿔야 합니다. 공유기에서 이 포트를 직접 포워딩하지 말고 Tailscale Funnel만 사용하세요.

2-B. Railway 배포 (레거시)

Procfile은 여전히 python server.py를 실행하므로, Railway로 배포하면 기본 6개 도구만 뜨고 법제처 8개 도구(server_ext.py)는 포함되지 않습니다. 크레딧이 소진되면 서버가 그대로 죽으므로 현재는 권장하지 않지만, 여전히 동작은 합니다.

1. 이 폴더를 GitHub 저장소로 올립니다.

2. Railway에서 "New Project" → "Deploy from GitHub repo" 선택.

3. Railway가 Procfile을 인식해서 python server.py로 자동 실행합니다. (PORT 환경변수는 Railway가 자동으로 주입합니다.)

4. 배포가 끝나면 Railway가 발급하는 도메인 뒤에 /mcp를 붙인 주소가 실제 MCP 서버 URL이 됩니다.

3. Claude에 커넥터로 등록

1. claude.ai 접속 → 프로필 → 설정(Settings) → 커넥터(Connectors)

2. "사용자 지정 커넥터 추가(Add custom connector)" 클릭

3. 이름: 원하는 이름으로 (현재 운영 커넥터명: Korea nts)

4. URL: 2번에서 확인한 .../mcp 주소 입력 후 저장 (현재 운영 주소: https://desktop-ika1349.tail81ecba.ts.net/mcp)

5. 도구 권한을 **"항상 허용"**으로 설정 (기본값 "승인 필요"는 매번 승인을 물어봄)

6. 완전히 새 대화창을 열어서 도구 목록에 뜨는지 확인 (커넥터를 새로 켠 직후에는 기존에 열려 있던 대화창에 반영되지 않을 수 있습니다)

4. 사용 예시 (Claude 채팅에서)

• "국세법령정보센터에서 조정대상지역 관련 질의회신이랑 심판례 찾아줘"

• "부당행위계산 부인 관련 최근 조세심판원 결정례 있는지 확인해줘. 2024년 이후만."

• "조심-2023-서-9465 판례 원문 보여줘" (사건번호 직접 조회)

• "양도소득세만 걸러서 다시 보여줘" (세목 필터)

• "취득세 중과 관련 지방세 심판례 찾아줘" (지방세 → olta_ruling_search)

• "재산세 과세기준일 관련해서 감사원 결정례 있는지 확인해줘" (지방세 → olta_ruling_search)

• "조정대상지역 관련해서 국세랑 지방세 심판례 다 찾아줘, 중복은 빼고" (→ nts_and_olta_precedent_search)

• "법령해석례에서 청산금 검색해줘" (→ law_interpretation_search)

• "소득세법 시행령 연혁 보여줘" (→ law_history_search)

• "부가가치세법 17조, 2008년 7월 15일 당시 조문 보여줘" (→ law_article_as_of)

• "법인세법 기본통칙 찾아줘" (→ admin_rule_search)

• "한·홍콩 조세조약 발효일 확인해줘" (→ treaty_search)

• "서울시 취득세 감면조례 찾아줘" (→ ordinance_search)

5. 서버 상태 독립 점검 (Claude 없이 확인하기)

Claude 채팅에서 도구가 안 잡히는 문제가 생겼을 때, 서버 자체 문제인지 Claude 쪽 문제인지를 빠르게 구분하기 위한 스크립트입니다. Claude를 거치지 않고 서버에 직접 MCP 프로토콜로 요청을 보내서 initialize → tools/list → tools/call까지 전체 흐름을 검증합니다.

python test_mcp_client.py

스크립트 기본값은 예전 Railway 서버 주소(https://web-production-10fe2.up.railway.app/mcp)로 남아 있는데, Railway는 크레딧 소진으로 더 이상 운영되지 않습니다 (2-A 참고). 현재 운영 중인 서버를 점검하려면 반드시 --url로 실제 주소를 지정하세요.

python test_mcp_client.py --url https://desktop-ika1349.tail81ecba.ts.net/mcp
python test_mcp_client.py --url http://127.0.0.1:8734/mcp

如果此脚本全部成功但在 Claude 聊天中却看不到工具，原因不在服务器，而是 Claude 这边连接器识别/缓存的问题。在这种情况下，请尝试以下步骤。

• 在一个全新的对话窗口中重新确认（刚刚开启连接器后，可能不会反映到现有对话窗口中）

• 在设置 → 连接器中删除该连接器并重新注册

• 如果仍然无效，请联系 support.claude.com（可能是 Claude 平台侧反馈延迟或错误）

工具参数参考

nts_ruling_search

nts_ruling_get_by_doc_no

olta_ruling_search (地方税)

nts_and_olta_precedent_search (国税+地方税整合，去重)

返回值包含 nts_precedent, olta_precedent, duplicates_removed(实际排除的重复数量)。

olta_collection_search (地方税深度探索)

olta_get_detail (地方税正文查询)

返回决定要旨·引用条文·处分概要·判断等正文全文文本。

court_case_search (法制处判例, server_ext.py)

court_case_detail (server_ext.py)

law_interpretation_search (法令解释例, server_ext.py)

law_history_search (法令沿革, server_ext.py)

law_article_as_of (特定时间点条文, server_ext.py)

admin_rule_search (行政规则, server_ext.py)

treaty_search (税收协定, server_ext.py)

ordinance_search (自治法规, server_ext.py)

已知限制（基于v5）

• 法制处(law.go.kr)的8个工具仅在通过 server_ext.py 运行时可用。如果仅单独运行 server.py，则只显示基本的6个。

• law.go.kr IP白名单：如果从未注册的IP调用，所有8个工具都会返回“认证失败”错误。需要在 open.law.go.kr → OpenAPI申请记录中首先注册服务器的公网IP。

• law.go.kr XML解析：使用基于正则表达式的轻量解析器处理响应。如果API响应结构发生变化（如标签名变更等），解析可能会出错。

• law_article_as_of：采用从沿革施行本中自动选择基准日期以下最大施行日期本的方式，如果存在多个同名的法令（本法/施行令/施行规则）混在一起，除非指定 law_id，否则可能会选择意外的施行版本。

• NTS税目过滤器：如果给出准确的税目名称（转让所得税等14种，参考 DATA_SOURCES.md 代码表），则应用服务器端过滤器；其他字符串则通过客户端后处理运行。

• NTS期间过滤器：已验证综合搜索API不存在期间参数（实际测量），因此 date_from/date_to 通过客户端过滤器处理。与最新顺序排序(sort=date_desc)结合使用会更稳定。

• 监察院审查请求(国税)：不包含在此服务器的范围内。（地方税监察院决定例通过 olta_ruling_search / olta_collection_search 覆盖。）

• nts_ruling_get_by_doc_no：由于未确认专用的详情查询API，因此采用将文档编号用作搜索词的方式实现。

• OLTA HTML解析：olta.re.kr以HTML响应，因此使用BeautifulSoup进行解析。如果网站界面结构发生变化（如类名 p.se_title, ul.search_out 等），解析可能会出错。

• **olta_ruling_search(综合搜索)每个类别仅返回3条预览。如果需要更多结果，请使用 olta_collection_search（每页10条，支持分页·期间·排序）。

• olta_get_detail正文查询仅支持税务审判院和宪法裁判所。法院判例由于详情URL需要2个参数而不被支持，有权解释类以要旨(summary)代替。

• 地方自治团体质疑回复：虽然存在于olta.re.kr内部代码表中，但未在综合搜索结果画面中显示，因此目前无法搜索。

• 去重：已验证国税/地方税税务审判院案件编号体系不同，实际上不会发生重复，nts_and_olta_precedent_search 的基于规范化的去重功能是安全措施。