nts-tax-mcp

This is an MCP (Model Context Protocol) server that allows you to use the integrated search of the National Tax Law Information System (taxlaw.nts.go.kr) and the Local Tax Law Information System (olta.re.kr) directly from Claude.

National Tax: Advance Rulings · Written Inquiries · Interpretative Rulings (National Tax Service/Ministry of Economy and Finance/Ministry of Government Legislation), Tax Tribunal Adjudications, National Tax Service Appeals, Court Precedents, Statutes

Local Tax (added in v3): Acquisition Tax · Property Tax · Automobile Tax · Local Income Tax · Registration and License Tax related Tax Tribunal Decisions, Board of Audit and Inspection Decisions, Constitutional Court Decisions, Court Precedents, Authoritative Interpretations by the Ministry of Government Legislation/Ministry of the Interior and Safety, Local Government Interpretative Rulings

Statutory Information Expansion (v5, added in the extended version server_ext.py): Search Supreme Court and lower court precedents, statutory history and articles at a specific point in time, statutory interpretations, administrative rules (Basic General Rules, etc.), tax treaties, and local ordinances (municipal ordinances) all through a single connector based on the National Law Information Center (law.go.kr) Open API.

v5 — Server Computer Migration + 8 New Ministry of Government Legislation (law.go.kr) Tools (2026-08)

Due to the depletion of Railway credits, the server went down (2026-08-08). It has been migrated to a permanently running self-hosted server computer exposed via Tailscale Funnel (completed 2026-08-09). During the migration, 8 tools using the Ministry of Government Legislation (law.go.kr) Open API were added, expanding the single connector to a total of 14 tools.

• Extended Entry Point: server_ext.py — It inherits the 6 tools (National Tax/Local Tax) from the existing server.py via from server import mcp and registers 8 additional Ministry of Government Legislation tools through the law_go_kr.py client. Since server.py itself is not modified, you can still run server.py directly if you only need the original 6 tools.

• 8 New Tools: court_case_search/court_case_detail (Ministry of Government Legislation Precedents), law_interpretation_search (Statutory Interpretations), law_history_search (List of Effective Versions of a Statute's History), law_article_as_of (Full text of an article in effect on a specific date — for verifying articles cited in rulings/precedents), admin_rule_search (Administrative Rules — Basic General Rules, Investigation Procedure Regulations, Notices), treaty_search (Tax Treaty Full Text/Effective Date), ordinance_search (Local Ordinances — Local Tax Reduction Ordinances, etc.)

• Prerequisite: The law.go.kr Open API only works from registered IP addresses. You must pre-register your server's public IP at open.law.go.kr → OpenAPI Application Details. If not registered, only the 8 Ministry of Government Legislation tools will show an "Authentication Failed" error, while the existing 6 National Tax/Local Tax tools will work normally. The environment variable LAW_API_OC (the institution code issued upon registering at law.go.kr, required) specifies the authentication account. As this is personally identifiable information, the actual value is not committed to this repository; it is loaded from a .gitignored local file located only on the server computer.

• Current Operation Method: On the server computer, run_server.bat (port 8734, executes server_ext.py) is run continuously via Windows Task Scheduler (nts-tax-mcp, automatic execution with SYSTEM privileges at boot). It is exposed externally at the fixed address https://desktop-ika1349.tail81ecba.ts.net/mcp via tailscale funnel --bg 8734. Initial setup is completed by running setup.ps1 once (automates downloading source from GitHub → installing dependencies → registering the task scheduler).

Related MCP server: LexGuard MCP

v5.1 — Article Parsing Bug Fix + Explicit Truncation Notification (2026-08-16)

• Bug Fix for Articles at Section Start: Fixed a bug where law_article_as_of would return only the heading (e.g., "Section 6 …") instead of the actual article text when querying an article that starts a section, subsection, or chapter (e.g., Income Tax Act Articles 104, 55). The cause was that the heading node appears first with the same <ArticleNumber> as the actual article. The fix filters out heading blocks that lack the article text string.

• Explicit Truncation + max_chars Exposure: Previously, if an article exceeded max_chars (default 6000 characters), the latter part (last paragraphs) was silently cut off. Now, if truncated, the response includes a "truncated" item indicating the total length and how to re-query. The max_chars parameter has been added to the law_article_as_of tool to allow retrieving the full text.

• Operational Note — .bat files MUST use CRLF line endings: If run_server.bat is saved with LF line endings, cmd.exe may skip lines, causing the PORT=8734 setting to be ignored and the server to start on the default port 8000 (a real incident — the Funnel was pointing to 8734, making the connector unresponsive). Depending on the editor, line endings can be changed to LF when saving. Always verify CRLF after modifying a .bat file.

v5.2 — Administrative Rule Article-Level Query (2026-08-17)

Added article (article number), max_chars, and start_char parameters to admin_rule_search. Previously, for large notices like the Foreign Exchange Transactions Regulations (Ministry of Finance and Economy Notice, approx. 300,000 characters), returning the full text was impossible, so only the first 10,000 characters were shown. Now, by specifying an article number, only that specific article is retrieved — e.g., for reporting overseas direct investment: serial=Foreign_Exchange_Transactions_Regulations_serial_number, article="9-5" (Article 9-5). If the article number is unknown, you can use the start_char offset to continue reading. If truncated, the "truncated" item in the response provides guidance for the next query.

Speed Improvement (2026-08-18): law.go.kr responses are now cached for 10 minutes. When querying consecutive articles of the same statute, the full XML of the law (e.g., Income Tax Act, 610,000 characters) is not re-downloaded (the second article onwards is returned instantly). Also fixed a page size parameter error (numOfRows→display) in the history query, reducing HTTP round trips from 5 to 1 (measured: cold query for 1 article from 1.1s to 0.6s).

v3 — Addition of Local Tax Law Information System (olta.re.kr)

National tax and local tax have completely different case numbering systems at the Tax Tribunal.

• National Tax: joshim-YYYY-RegionalOfficeCode-NNNN (e.g., joshim-2023-seo-9465)

• Local Tax: joshimYYYYjiNNNN (e.g., joshim2026ji0284)

In practice, searching both systems with the same keyword shows that Tax Tribunal decisions rarely overlap (the National Tax Service system does not index local tax cases). Nevertheless, to be safe, the nts_and_olta_precedent_search tool normalizes document numbers, removes duplicates, and reports the duplicates_removed count.

File Structure

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 처리, 서버컴퓨터에서 직접 생성

Provided Tools

server.py exposes the basic 6 tools, while server_ext.py exposes the basic 6 + 8 Ministry of Government Legislation tools = a total of 14 tools. The actual production server (server computer) runs server_ext.py, making all 14 tools available.

Basic 6 Tools (National Tax/Local Tax, server.py)

Extended 8 Tools (Ministry of Government Legislation law.go.kr, added only in server_ext.py)

v4 — Deep Search Features (Full Implementation of Improvement Candidates)

• OLTA Pagination, Period, Sorting: Use olta_collection_search to deeply explore a specific category in units of 10 items. Period (YYYYMMDD) and newest-first sorting are processed server-side for accuracy.

• OLTA Full Text Retrieval: Use olta_get_detail to retrieve the full text of Tax Tribunal and Constitutional Court decisions (Decision Summary, Disposition Overview, Judgment).

• NTS Server-Side Tax Type Filter: If you provide an exact tax type name (Capital Gains Tax, Corporate Tax, Value Added Tax, Inheritance and Gift Tax, Comprehensive Real Estate Tax, etc. — 14 types) to tax_type_filter, the server-side code filter is automatically applied, accurately filtering based on the entire dataset.

Refer to DATA_SOURCES.md for detailed data specifications and code tables.

v2.1 Bug Fixes (Important)

Issues discovered while working on the client/ folder have been fixed.

• Bug where date filters (date_from/date_to) broke the search entirely — The integrated search page on taxlaw.nts.go.kr does not have a period filter UI. The bltnStrtDtm/bltnEndDtm server parameters, which were added based on guesswork in the previous version, were treated as invalid values, causing search results to return 0 items entirely. These parameters have been removed and replaced with a client-side filter that filters results by the date field after retrieval.

• Also fixed an issue where search term highlight markers (<!HS>, <!HE>) were not being removed from the document number (doc_no) field, causing exact matching in nts_ruling_get_by_doc_no to fail.

MCP Connector Bypass Independent Client (client/)

An independent client that can connect directly to the server for searching without going through MCP has been added to the client/ folder, for use when the Claude connector connection is unstable. See client/README.md for usage.

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

v2 Improvements

The following items have been improved since the initial version.

1. Local Execution Verification

pip install -r requirements.txt
python server.py

By default, it serves via streamable-http at http://0.0.0.0:8000/mcp. The port can be changed via the environment variable PORT.

PORT=8765 python server.py

Environment Variable Options

2. Deployment

2-A. Current Operation Method — Server Computer Always On + Tailscale Funnel (2026-08~)

After the server went down due to Railway credit depletion (2026-08-08), it was switched to a method using a permanently running self-hosted server computer. All 14 tools (server_ext.py) are operated this way.

1. Run setup.ps1 once in an administrator PowerShell on the server computer — it downloads the source from GitHub, installs dependencies, registers nts-tax-mcp (automatic execution with SYSTEM privileges at boot) in Windows Task Scheduler, and starts it immediately.

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

2. run_server.bat sets PORT=8734 and executes server_ext.py (log: server.log). LAW_API_OC is not written directly in this file; it is loaded from a .gitignored local file (local_env.bat — containing a single line set LAW_API_OC=your_institution_code). If this file is missing, only the 8 Ministry of Government Legislation tools will not work; the basic 6 tools will function normally.

3. Install Tailscale, log in, and expose the server externally at a fixed address using Funnel.

   tailscale funnel --bg 8734

4. Actual MCP server URL (fixed): https://desktop-ika1349.tail81ecba.ts.net/mcp

If you change the port, you must change both PORT in run_server.bat and the target port of tailscale funnel. Do not forward this port directly on your router; only use Tailscale Funnel.

2-B. Railway Deployment (Legacy)

The Procfile still executes python server.py, so deploying on Railway will only expose the basic 6 tools; the 8 Ministry of Government Legislation tools (server_ext.py) are not included. If credits are depleted, the server will simply stop. This method is currently not recommended, but it still works.

1. Upload this folder to a GitHub repository.

2. On Railway, select "New Project" → "Deploy from GitHub repo".

3. Railway will recognize the Procfile and automatically run python server.py. (Railway automatically injects the PORT environment variable.)

4. After deployment, the address issued by Railway with /mcp appended becomes the actual MCP server URL.

3. Registering as a Connector in Claude

1. Go to claude.ai → Profile → Settings → Connectors

2. Click "Add custom connector"

3. Name: Any desired name (current operational connector name: Korea nts)

4. URL: Enter the .../mcp address confirmed in step 2 and save (current operational address: https://desktop-ika1349.tail81ecba.ts.net/mcp)

5. Set tool permissions to "Always allow" (the default "Require approval" will ask for permission each time)

6. Open a completely new conversation window and verify that the tools appear in the tool list (after turning on a new connector, it may not be reflected in previously open conversation windows)

4. Usage Examples (in Claude Chat)

• "Find interpretative rulings and tribunal decisions related to adjustment target areas from the National Tax Law Information Center"

• "Check if there are recent Tax Tribunal decisions related to the denial of unfair calculation. Only from 2024 onwards."

• "Show me the full text of precedent joshim-2023-seo-9465" (direct query by case number)

• "Filter and show me only Capital Gains Tax" (tax type filter)

• "Find local tax tribunal decisions related to heavy acquisition tax" (Local Tax → olta_ruling_search)

• "Check if there are Board of Audit and Inspection decisions related to the property tax base date" (Local Tax → olta_ruling_search)

• "Find all national and local tax tribunal decisions related to adjustment target areas, excluding duplicates" (→ nts_and_olta_precedent_search)

• "Search for 'liquidation money' in statutory interpretations" (→ law_interpretation_search)

• "Show me the history of the Enforcement Decree of the Income Tax Act" (→ law_history_search)

• "Show me Article 17 of the Value Added Tax Act as it was on July 15, 2008" (→ law_article_as_of)

• "Find the Basic General Rules for the Corporate Tax Act" (→ admin_rule_search)

• "Check the effective date of the Korea-Hong Kong tax treaty" (→ treaty_search)

• "Find Seoul City's acquisition tax reduction ordinance" (→ ordinance_search)

5. Independent Server Status Check (Verification Without Claude)

This script is for quickly distinguishing whether a problem with tools not appearing in Claude chat is due to the server itself or a Claude-side issue. It sends MCP protocol requests directly to the server without going through Claude, verifying the entire flow from initialize → tools/list → tools/call.

python test_mcp_client.py

The script's default value is the old Railway server address (https://web-production-10fe2.up.railway.app/mcp), but Railway is no longer operational due to credit depletion (see 2-A). To check the currently operational server, you must specify the actual address using --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

If all these scripts succeed but the tools are not visible in Claude Chat, the cause is not the server but a connector recognition/caching issue on Claude's side. In this case, try the following.

• Check again in a completely new conversation window (it may not be reflected in existing conversations right after turning on the connector)

• Go to Settings → Connectors, delete the connector, and re-register it

• If it still doesn't work, contact support.claude.com (it may be a delay/bug on the Claude platform side)

Tool Parameter Reference

nts_ruling_search

nts_ruling_get_by_doc_no

olta_ruling_search (Local Tax)

nts_and_olta_precedent_search (National Tax + Local Tax Integrated, Deduplication)

The return value includes nts_precedent, olta_precedent, and duplicates_removed (actual number of duplicates removed).

olta_collection_search (Local Tax In-depth Search)

olta_get_detail (Local Tax Full Text Retrieval)

Returns the full text of the decision summary, referenced provisions, disposition overview, judgment, etc.

court_case_search (MOLE Precedent, server_ext.py)

court_case_detail (server_ext.py)

law_interpretation_search (Statutory Interpretation Cases, server_ext.py)

law_history_search (Statutory History, server_ext.py)

law_article_as_of (Article as of a Specific Date, server_ext.py)

admin_rule_search (Administrative Rules, server_ext.py)

treaty_search (Tax Treaties, server_ext.py)

ordinance_search (Local Ordinances, server_ext.py)

Known Limitations (as of v5)

• The 8 MOLE (law.go.kr) tools are only available when running server_ext.py. Running only server.py alone exposes only the basic 6 tools.

• law.go.kr IP whitelist: If called from an unregistered IP, all 8 tools return an "Authentication Failed" error. You must first register the server's public IP at open.law.go.kr → OpenAPI Application History.

• law.go.kr XML parsing: The response is processed by a regex-based lightweight parser. If the API response structure changes (e.g., tag name changes), parsing may break.

• law_article_as_of: It automatically selects the version with the latest effective date on or before the reference date among historical versions. If multiple statutes with the same name (main act/enforcement decree/enforcement rules) are mixed, an unintended version may be selected unless law_id is specified.

• NTS tax type filter: If you provide an exact tax type name (14 types including Capital Gains Tax, see code table in DATA_SOURCES.md), a server-side filter is applied; other strings are handled by client-side post-processing.

• NTS date filter: It has been confirmed (by measurement) that the integrated search API does not have a date parameter, so date_from/date_to are handled as client-side filters. Using them together with newest-first sorting (sort=date_desc) is more reliable.

• Board of Audit and Inspection review requests (national tax): Not included in the scope of this server. (Local tax BAI decisions are covered by olta_ruling_search / olta_collection_search.)

• nts_ruling_get_by_doc_no: No dedicated detail retrieval API has been identified, so it is implemented by using the document number as a search term.

• OLTA HTML parsing: olta.re.kr responds with HTML, so it is parsed with BeautifulSoup. If the site's screen structure changes (class names like p.se_title, ul.search_out, etc.), parsing may break.

• olta_ruling_search (integrated search) returns only 3 previews per category. If you need more results, use olta_collection_search (10 items per page, supports pagination, date range, and sorting).

• olta_get_detail full text retrieval supports only the Tax Tribunal and Constitutional Court. Court precedents are not supported because the detail URL requires two parameters; authoritative interpretations are replaced with a summary.

• Local government inquiry replies: They exist in the olta.re.kr internal code table but are not exposed on the integrated search results screen, so they cannot currently be searched.

• Deduplication: It has been confirmed by measurement that actual duplicates do not occur because the case number systems of the National Tax and Local Tax Tribunals are different; the normalization-based deduplication in nts_and_olta_precedent_search is a safety measure.