nts-taxlaw-mcp

An MCP server that directly queries the National Tax Service Tax Law Information System (https://taxlaw.nts.go.kr).

It is implemented in Python and FastMCP, and uses the National Tax Service's own lookup endpoints rather than going through the Ministry of Government Legislation mirror (ntsCgmExpc).

• Look up the latest tax law interpretation rulings

• Structure full-text details such as replies, decisions, and conclusions

• Exact lookup by document number

• Search precedents, decisions, and administrative interpretation standards

• Structured responses including the source and the type of legal basis

The existing korean-law-mcp can retrieve lists of National Tax Service interpretation rulings due to the nature of the Ministry of Government Legislation OPEN API, but it has limitations in retrieving detailed full text. nts-taxlaw-mcp queries the National Tax Service original source directly to provide document-number lookup and full-text retrieval.

1. Supported data

Volume

Measured as of August 2026.

| Data | Count | | ---- ------- | ------: | | Written inquiries | 132,638 | | Pre-tax answers | 5,117 | | Tax-base consultation | 1,036 | | Notice-based written inquiries | 14 | | Statute interpretation arrangements | 996 | | Tax dispute | 518 | | Appeals | 1,478 | | Review requests | 22,233 | | Trial requests | 71,349 | | Precedents | 55,860 | | Constitutional Court | 355 |

Data not supported

See docs/INVESTIGATION.md for additional research.

Related MCP server: korean-engineering-mcp

2. Data source

All data is retrieved from the National Tax Service Tax Law Information System.

https://taxlaw.nts.go.kr

• Uses the public query endpoint POST /action.do

• No login, CAPTCHA, or access control workarounds

• No separate session, cookie, or authentication key required

• All responses include source traceability information

{
  "sourceAgency": "국세청",
  "sourceSystem": "국세법령정보시스템",
  "sourceId": "200000000000022584",
  "documentNumber": "서면-2026-법규재산-0119",
  "sourceUrl": "https://taxlaw.nts.go.kr/qt/USEQTA002P.do?ntstDcmId=200000000000022584",
  "retrievedAt": "2026-08-19T13:34:58Z"
}

3. Document number lookup

Normalize the formatting differences of document numbers to retrieve the same document.

서면-2026-법규재산-0119
서면 2026 법규재산 0119
서면2026법규재산0119
서면서면-2026-법규재산-0119
질의회신 서면-2026-법규재산-0119
질의회신서면-2026-법규재산-0119
국세청 서면-2026-법규재산-0119

The recognized document number formats are as follows.

A and B are distinguished by whether the second element is a four-digit year.

Exact Match Principle

정확히 일치
→ found: true
→ exactMatch: true
→ document 반환

일치 없음
→ NOT_FOUND
→ similarDocuments 별도 반환

Documents with only a partial match are not returned as an answer.

lookup_tax_document("법규재산-0119")

→ [NOT_FOUND]

similarDocuments:
  · 서면-2026-법규재산-0119
  · 서면-2015-징세-0119
  · 기준-2023-법규부가-0044
  · 적부-국세청-2020-0119

similarDocuments is search assistance information and should not be considered the requested document.

If only the zero-padding differs, such as 0119 vs. 119, the document number is treated as the same. Normalization is used only to expand lookup candidates; the final response returns the original National Tax Service document number as-is.

4. Keyword search

It is based on the actual search results of the Tax Law Information System, and applies its search syntax.

It is used in MCP as follows.

{"query": "상속 공동상속주택"}                  # AND
{"query": "상속 증여", "match": "any"}         # OR
{"query": "상속", "exclude": ["증여"]}         # NOT
{"query": '"공동상속주택 소수지분" 양도'}       # 구절 검색

Note the following when searching:

• The OR operator uses the ASCII pipe |.

• ¦ (U+00A6) does not act as OR.

• Passing an invalid sort field returns 0 results rather than an error.

• The server only uses DCM_RGT_DTM, FRS_RGT_DTM, and SCORE, which have been verified for actual behavior.

5. Installation

You do not need to install Python directly or create a virtual environment manually. uv manages the required Python and packages.

5.1 Install uv

Windows

PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

If script execution is restricted by corporate policy:

winget install --id=astral-sh.uv -e

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, reopen the terminal and verify.

uv --version

5.2 Install the server

You can install directly from the GitHub address.

uv tool install git+<GitHub 주소>

After installing, you can run the nts-taxlaw-mcp command from any path.

Check the installation location:

(Get-Command nts-taxlaw-mcp).Source

which nts-taxlaw-mcp

Typical installation paths:

Update:

uv tool upgrade nts-taxlaw-mcp

Uninstall:

uv tool uninstall nts-taxlaw-mcp

5.3 Install from source

If you want to modify the code or run tests, download the repository.

git clone <GitHub 주소>
cd nts-taxlaw-mcp
uv sync

uv sync performs the following:

• Checks and installs a Python compatible with requires-python = ">=3.11"

• Creates .venv in the project directory

• Installs dependencies based on uv.lock

There is no need to activate the virtual environment yourself. Subsequent commands are run with uv run.

If git is unavailable, you can also download the repository via GitHub's Code > Download ZIP, unzip, and run uv sync.

Verify it works:

uv run nts-taxlaw-mcp --help
uv run python scripts/compare_with_site.py

5.4 PATH check

If uv or nts-taxlaw-mcp is not found immediately after installation, reopen the terminal and check again.

uv tool update-shell

On Windows, check with an absolute path:

& "$env:USERPROFILE\.local\bin\uv.exe" --version

macOS / Linux:

~/.local/bin/uv --version

6. Connecting Claude Code

When installed with uv tool

claude mcp add nts-taxlaw -- nts-taxlaw-mcp

If the command is not found, confirm the install location and then set the absolute path.

claude mcp add nts-taxlaw -- "C:\Users\<사용자>\.local\bin\nts-taxlaw-mcp.exe"

When running from the repository

claude mcp add nts-taxlaw -- uv run --directory /절대경로/nts-taxlaw-mcp nts-taxlaw-mcp

Verify registration:

claude mcp list

HTTP connection

nts-taxlaw-mcp --http --port 8000

Claude Code registration:

claude mcp add --transport http nts-taxlaw http://127.0.0.1:8000/mcp

7. Connecting Claude Desktop

Settings file:

For Claude Desktop, it is more reliable to specify the absolute path of the executable.

Windows

uv tool installation:

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "C:\\Users\\<사용자>\\.local\\bin\\nts-taxlaw-mcp.exe"
    }
  }
}

Running from the repository:

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "C:\\Users\\<사용자>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\<사용자>\\nts-taxlaw-mcp",
        "nts-taxlaw-mcp"
      ]
    }
  }
}

In JSON, write Windows backslashes as \\ in the path. Using / also works.

macOS

uv tool installation:

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "/Users/<사용자>/.local/bin/nts-taxlaw-mcp"
    }
  }
}

Running from the repository:

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "/Users/<사용자>/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/<사용자>/nts-taxlaw-mcp",
        "nts-taxlaw-mcp"
      ]
    }
  }
}

To verify the actual path:

(Get-Command nts-taxlaw-mcp).Source

which nts-taxlaw-mcp

Using together with korean-law-mcp

The recommended configuration is to look up statute, enforcement decree, and enforcement rule text via korean-law-mcp, and retrieve NTS-specific materials via nts-taxlaw-mcp.

{
  "mcpServers": {
    "korean-law": {
      "command": "npx",
      "args": ["-y", "korean-law-mcp"],
      "env": {
        "LAW_OC": "발급받은-인증키"
      }
    },
    "nts-taxlaw": {
      "command": "C:\\Users\\<사용자>\\.local\\bin\\nts-taxlaw-mcp.exe"
    }
  }
}

pip + venv

In environments where uv is not available, you can install Python 3.11 or later directly and run it in the traditional way.

git clone <GitHub 주소>
cd nts-taxlaw-mcp

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

python -m nts_taxlaw_mcp --help

Activate the Windows virtual environment:

.venv\Scripts\activate

For Claude Desktop, specify the absolute path to the Python executable inside the virtual environment.

{
  "mcpServers": {
    "nts-taxlaw": {
      "command": "/절대경로/nts-taxlaw-mcp/.venv/bin/python",
      "args": ["-m", "nts_taxlaw_mcp"]
    }
  }
}

8. Environment variables

All items are optional and the defaults are sufficient for normal use.

9. MCP tools

A total of 9 tools are provided.

If you know the document number, use lookup_tax_document first.

get_tax_document unifies detailed retrieval of interpretations and rulings into one tool. Since the Tax System Information System uses the same detailed lookup action regardless of document type, it is not split into separate detail tools.

Usage examples

Document number lookup:

{
  "name": "lookup_tax_document",
  "arguments": {
    "document_number": "서면-2026-법규재산-0119"
  }
}

Example response:

[OK]

found: true
exactMatch: true

서면-2026-법규재산-0119
질의회신 | 양도소득세 | 2026-08-11 | nts_ruling

title:
인구감소지역 내 취득한 분양권이 ’27.1.1.이후 주택으로 전환된 경우 조특법§71의2 적용 여부

relatedLaws:
- 조세특례제한법 제71조의2
- 조세특례제한법 시행령 제68조의2

sections:
- facts
- question
- relatedLawsText

Search precedents and rulings:

{
  "name": "search_tax_decisions",
  "arguments": {
    "query": "공동상속주택",
    "type": "court",
    "result": ["국승"],
    "limit": 3
  }
}

Search basic rules:

{
  "name": "search_tax_guidance",
  "arguments": {
    "kind": "basic_ruling",
    "law_name": "상속세 및 증여세법",
    "query": "상속재산"
  }
}

Collect legal bases for a tax question:

{
  "name": "tax_research",
  "arguments": {
    "question": "부모가 자녀에게 시가보다 낮은 가격으로 아파트를 양도하면 증여세가 발생하는지"
  }
}

10. Legal basis classification

Tax materials are returned classified by the nature of the legal basis.

National Tax Service rulings are associations of interpretation for tax authorities and do not bind courts. Basic rules and enforcement standards are internal execution standards, not statutes themselves.

11. Error handling

Errors distinguish a grade in which the data does not actually exist from failures due to problems with the original server.

Error responses also include guardrail information that prevents the model from generating unverified body or conclusions.

Even if an HTTP 200 response is received, it is treated as a temporary outage if the content is a maintenance HTML page or the body is abnormally empty, and retried.

12. Request limits and caching

The server limits call volume and reduces repeated lookups to avoid excessive requests to the National Tax Service system.

Request limits

• Default period limit: 60 requests per minute

• Burst allowance: 20 requests per burst

• Uses the token bucket method for multi-row(z)

Cache

Concurrent request handling

If the same identical request arrives simultaneously, the original Tax Service system call is executed only once and the result is shared.

HTTP connection reuse

Uses the httpx keep-alive connection pool.

13. Disclaimer

• This server is a data access layer for searching and structuring NTS original text, and does not provide legal advice or tax advice.

• Interpretations and rulings are decided based on the facts of each individual case.

• NTS interpretations do not bind the courts.

• Basic rules and enforcement standards are internal guidelines, not regulations.

• For amended tax law, the effective date must be confirmed separately.

• The accuracy and currency of the data follow the update status of the Tax Law Information System.

• If the legal effect matters, you need to verify the original text on the Tax Law Information System.

• Actions with legal effect, such as filing returns or any protest / dispute resolution, require the substantiated review from qualified professionals such as tax accountants or attorneys.

License

MIT

See NOTICE for data source attribution.