# korean-tax-mcp

> MCP server that gives AI agents the sources of Korean (South Korea) tax law: statutes as in force on any date, National Tax Service (NTS) rulings, court and Tax Tribunal decisions, basic rules, 96 tax treaties with treaty withholding rates, a resident/non-resident test, transfer pricing references and NTS guidebooks. Read-only except `build_tax_memo`, which writes one Word file locally; every tool takes lang="en".

Install: `uvx korean-tax-mcp` (Claude Code: `claude mcp add korean-tax -- uvx korean-tax-mcp`). Most tools need no key. Statute tools (law_article, find_article, article_history, article_addenda, research_issue, verify_statement, judge_options) and Tax Tribunal tools (search_tribunal_decisions, get_tribunal_decision) need a free law.go.kr Open API key in `LAW_OC` (see the key table in the README). `UPSTAGE_API_KEY` is optional (Solar summaries and translation; otherwise your own AI does it).

Registry name: `io.github.UpstageAI/korean-tax-mcp` · PyPI: `korean-tax-mcp` · License: MIT

Tool names and descriptions start with English; the rest of each description and most source texts are Korean. Statute and treaty tools return official English texts where they exist.

Agent builders: Anthropic's BM25 tool search (`tool_search_tool_bm25`) does not match Hangul queries — search with English keywords (tool descriptions start with English) or use the regex tool search (`tool_search_tool_regex`), which matches Korean terms (checked 2026-11-14).

## Which tool for which question

| Question | Tool |
|---|---|
| I have an issue but no article number — what rulings and cases exist? | `search_tax_rulings` (one issue) or `search_rulings_by_issue` (several issues), then `get_tax_ruling` for the full text |
| Which article governs this? | `find_article`, then `law_article` |
| What did the article say on a given date (tax year end, payment date)? | `law_article` with `as_of` (YYYYMMDD) |
| When did an article change, and from when does the amendment apply? | `article_history`, then `article_addenda` |
| How has the NTS interpreted a specific article? | `rulings_by_article`, `basic_rules`, `execution_standards` |
| Everything that applied to an issue in a past tax year | `research_issue` |
| Which tax year / VAT period does a dated fact fall into? | `timing_rules` |
| Taxpayer wins vs losses on one issue | `compare_outcomes`; your own facts against rulings: `compare_with_case` |
| Tax Tribunal decisions, incl. local taxes | `search_tribunal_decisions`, `get_tribunal_decision` |
| Is this person a Korean tax resident? Treaty tie-breaker? | `residency_check` (rules, no key), `residency_report` (written review) |
| Does a foreign company / nonresident have a permanent establishment (PE) in Korea under domestic law? | `permanent_establishment_guide` (then `tax_treaty` for the treaty PE article) |
| What does the Korea–X tax treaty say? | `tax_treaty` |
| Treaty cap on dividends, interest, royalties to country X | `treaty_withholding_rates` |
| Withholding on royalties (patent, know-how, trademark, copyright, software) paid from Korea to a foreign company: source, rate, procedure, gross-up | `royalty_withholding_guide` (then `treaty_withholding_rates`, `tax_treaty`) |
| Transfer pricing rule and method, FAR analysis, Local File outline, decisions, OECD Guidelines | `transfer_pricing_guide`, `transfer_pricing_far`, `transfer_pricing_report`, `transfer_pricing_cases`, `oecd_tp_guidelines` |
| What do NTS guidebooks say (overseas expansion, foreign corporations, filing guides, APA reports)? | `search_nts_publications` |
| Rate tables, useful-life tables, official forms | `search_forms` |
| Requirements that change by tax year (R&D credit, employment credit, SME incentives, family business succession, one-house CGT exemption, VAT exemption/zero rate) | `rnd_credit_requirements_guide`, `employment_credit_requirements_guide`, `sme_tax_incentives_guide`, `family_business_succession_guide`, `one_house_exemption_guide`, `vat_exempt_zero_rate_guide` |
| Income type rules (wage incl. flat rate for foreign employees, interest, dividend, business, pension, other, retirement income) | `wage_income_guide`, `interest_income_guide`, `dividend_income_guide`, `business_income_guide`, `pension_income_guide`, `other_income_guide`, `retirement_income_guide` |
| Tax crime provisions and investigation procedure | `tax_crime_guide`, `tax_crime_procedure_guide`; nominee-held property: `nominee_trust_guide` |
| Do cited document numbers and articles exist? Does a statement match the text? | `verify_citations`, `verify_statement`, `judge_options` |
| Write a tax memo, opinion, review note or report as a finished Word (.docx) file (English or Korean) with a fixed order of reasoning and real footnotes — keywords: memo, Word, docx, report, 메모, 보고서. Do not write your own docx script | `tax_memo_guide` (logic line, schema, example) → evidence tools here + calculators in korean-tax-calc-mcp → `build_tax_memo` (validates, writes .docx). If an Excel file goes with the memo, build the workings workbook yourself (amounts from the calculators), save it and check the amount cells with `verify_workbook` before writing the memo (`export_workbook` only when a statutory form is needed as Excel; both in korean-tax-calc-mcp) and record the result in the structure's `workings_check` — the memo check warns when it is missing |
| NTS 2025 casebook of interpretations | `casebook_search` |
| Your own PDFs (e.g. OECD Guidelines you downloaded) | `search_local_documents` |

## For foreign companies, expats and Korean subsidiaries

- Residency of expats and seconded staff: `residency_check` → `residency_report`
- Treaty text and withholding caps: `tax_treaty`, `treaty_withholding_rates`
- Cross-border royalty withholding (requirements, decision path, 2025 en banc decision on unregistered patents): `royalty_withholding_guide`
- Permanent establishment under domestic law: `permanent_establishment_guide`, then `tax_treaty` for the treaty PE article
- Intercompany pricing: `transfer_pricing_guide`, `transfer_pricing_far`, `transfer_pricing_report`
- NTS guides for foreign corporations and companies expanding overseas: `search_nts_publications`
- Cross-border rulings: `search_tax_rulings` with `tax="국조"` (international tax)
- Worked examples: [Use cases](https://upstageai.github.io/korean-tax-mcp/use-cases/)

## Companion servers

- [korean-tax-calc-mcp](https://github.com/UpstageAI/korean-tax-calc-mcp) (139 tools): computes the amounts (corporate, income, VAT, withholding incl. non-residents, VAT reverse charge, expat cost recharge, foreign subsidiary dividends, foreign tax credit, CFC) and fills statutory forms. `uvx korean-tax-calc-mcp`
- [korean-report-hwpx](https://github.com/UpstageAI/korean-report-hwpx): turns findings into a Korean government-format report or press release (HWPX). `uvx korean-report-hwpx`

## Limits

- Not tax advice. Results are reference material; verify against the statute text and the linked original source, and consult a qualified professional.
- Rulings and court decisions reflect the law at the time they were issued. Check the article in force for your tax year with `law_article` (`as_of`).
- Cite only document numbers that appear in tool results.
- Bundled tables (requirement guides, transfer pricing, timing rules, residency rules) state the statute version they were checked against.
- Sources are public services (law.go.kr, taxlaw.nts.go.kr); they can be slow or under maintenance.

## Docs

- [Site](https://upstageai.github.io/korean-tax-mcp/)
- [README (English)](https://github.com/UpstageAI/korean-tax-mcp/blob/main/README-EN.md)
- [README (Korean)](https://github.com/UpstageAI/korean-tax-mcp/blob/main/README.md)
- [CHANGELOG](https://github.com/UpstageAI/korean-tax-mcp/blob/main/CHANGELOG.md)
- [PyPI: korean-tax-mcp](https://pypi.org/project/korean-tax-mcp/)
- [MCP Registry: io.github.UpstageAI/korean-tax-mcp](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.UpstageAI/korean-tax-mcp)
