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 の正規化ベースの重複除去は安全装置です。