korean-tax-calc-mcp

# korean-tax-calc-mcp

> MCP server that computes Korean (South Korea) tax amounts with statutory citations: corporate and income tax, VAT, withholding (incl. payments to non-residents and foreign corporations), VAT reverse charge, expat cost recharges, dividends from foreign subsidiaries, foreign tax credits, CFC rules, transfer pricing ranges, penalties, deadlines, inheritance and gift tax, and tax-audit checks. 140 tools, tax years 2016–2026, deterministic code (no generative AI except 3 optional PDF tools).

Install: `uvx korean-tax-calc-mcp` (Claude Code: `claude mcp add korean-tax-calc -- uvx korean-tax-calc-mcp`). No key needed. Optional: `LAW_OC` (law.go.kr, two audit tools), `UPSTAGE_API_KEY` (PDF table extraction), `VWORLD_KEY` (official property price lookup).

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

Tool names are English, and every tool description starts with an English line followed by the Korean term; `find_tool` accepts English queries. Result keys and enum values are mostly Korean (e.g. income_kind "사용료" = royalties, recipient_type "법인" = corporation) — read each tool's input schema and see the [glossary](https://github.com/UpstageAI/korean-tax-calc-mcp/blob/main/docs/glossary_ko_en.md). If you do not know which tool fits, call `find_tool` first.

If you build an agent with Anthropic's BM25 tool search (`tool_search_tool_bm25`), it does not match Hangul queries (checked 2026-11-14: Korean words present verbatim in descriptions returned 0 results; English matched). Search with English keywords — every tool description starts with an English line — or use the regex tool search (`tool_search_tool_regex`), which matches Korean terms. If unsure which tool to use, call `find_tool` first — it accepts Korean and English queries.

## Which tool for which question

| Question | Tool |
|---|---|
| I don't know which tool to use | `find_tool` |
| Withholding tax on interest, dividends, royalties, services paid to a non-resident or foreign corporation (with treaty rate) | `nonresident_withholding` (get the treaty cap from korean-tax-mcp `treaty_withholding_rates`) |
| Domestic withholding; monthly withholding return | `withholding_tax`, `daily_worker_withholding`, `withholding_return` |
| VAT reverse charge on services bought from a foreign supplier without a Korean place of business | `vat_reverse_charge`; foreign-currency amounts: `vat_foreign_currency_base` |
| Charging the cost of employees seconded to an overseas subsidiary | `expat_cost_recharge` |
| Dividends from a foreign subsidiary: 95% exclusion, 100% for 2026 receipts (Restriction of Special Taxation Act Art. 23-2), or foreign tax credit | `foreign_subsidiary_dividend` |
| Foreign tax credit — corporation / individual | `foreign_tax_credit`, `individual_foreign_tax_credit` |
| Foreign worker: 19% flat tax option vs regular rates; foreign engineer/researcher income tax reduction | `foreign_worker_flat_tax`, `foreign_expert_income_reduction` |
| Nonresident or foreign corporation selling Korean real estate or shares — withholding | `nonresident_capital_gains_withholding` |
| Inheritance tax for a nonresident decedent; gift tax for a nonresident donee | `nonresident_inheritance_gift` |
| Branch profits tax on a foreign corporation's Korean branch (PE test: korean-tax-mcp `permanent_establishment_guide`) | `branch_profits_tax` |
| Departure (exit) tax when a resident major shareholder emigrates | `emigration_exit_tax` |
| Controlled foreign corporation (CFC) deemed dividend and later actual dividend or share sale | `cfc_deemed_dividend`, `cfc_actual_dividend`, `cfc_share_disposal` |
| Transfer pricing: arm's length range and adjustment, comparable screening, international transaction statement | `arm_length_range`, `tp_comparable_screen`, `international_transaction_statement` |
| Thin capitalization (interest to foreign controlling shareholders) | `thin_capitalization` |
| Overseas direct investment reporting, overseas subsidiary statements, overseas financial accounts | `foreign_exchange_reporting`, `overseas_subsidiary_statement`, `overseas_account_reporting` |
| Filing obligations (external audit, external tax adjustment, international transaction data) | `corporate_filing_obligations` |
| Liquidating a foreign subsidiary | `foreign_subsidiary_liquidation` |
| Corporate tax from the tax base; tax adjustments | `corporate_tax`, `income_adjustment_total`, `tax_adjustment_schedule`, `minimum_tax_adjustment` |
| Deductibility limits (entertainment, donations, bad debts, business cars, depreciation, retirement allowances) | `entertainment_limit`, `entertainment_adjustment`, `donation_limit`, `bad_debt_allowance`, `bad_debt_adjustment`, `business_car_expense`, `depreciation_adjustment`, `retirement_allowance_adjustment` |
| Related-party loans and unfair transactions | `deemed_interest`, `unfair_transaction`, `nonbusiness_interest_disallowance`, `related_judge` |
| Tax credits and reductions (R&D, investment, employment, startup, SME) | `rnd_tax_credit`, `integrated_investment_credit`, `integrated_employment_credit`, `employment_increase_credit`, `startup_tax_reduction`, `sme_special_tax_reduction`, `sme_status` |
| Loss carryforward / carryback | `loss_carryforward_limit`, `loss_carryforward_ledger`, `loss_carryback_refund` |
| Individual income tax, wage income, year-end settlement | `income_tax`, `wage_income_tax`, `earned_income_gross_pay`, `personal_deduction`, `special_tax_credit`, `child_tax_credit` |
| Financial income, dividends received, deemed dividends | `financial_income_aggregate`, `dividend_tax_credit`, `dividend_received_deduction`, `deemed_dividend_bonus_shares`, `deemed_dividend_capital_reduction` |
| VAT return items and the general VAT return | `vat_input_tax_deduction`, `common_input_tax`, `vat_supply_timing`, `vat_return_general`, `simplified_vat_return` |
| Capital gains on real estate and shares | `capital_gains_income`, `capital_gains_tax`, `stock_capital_gains_tax`, `stock_major_shareholder` |
| Inheritance and gift tax, valuation | `inheritance_tax`, `gift_tax`, `inheritance_gift_valuation`, `unlisted_stock_valuation` |
| Penalties, assessment period, refund claim deadline | `underreporting_penalty`, `late_payment_penalty`, `withholding_late_payment_penalty`, `invoice_penalty`, `assessment_limitation`, `refund_claim_deadline` |
| Tax-audit checks (return precheck, tunnelling gift) | `return_precheck`, `tunnelling_gift`, `tunnelling_gift_nts` |
| Excel / xlsx / spreadsheet / workings or report (엑셀, 계산 근거): build the workbook yourself (layout, sheets and names are yours — only the lines the reader needs), take every amount from a calculation tool call, save it, then check the amount cells | `verify_workbook` with `path`, `checks=[{cell, call}]` — `call` is the `호출_id` (e.g. "c7") on each calculation result; `key` optional |
| Check every amount cell of a saved workbook against the calls made so far (same-value matches are marked "auto" and counted separately) | `verify_workbook` with `path`, `auto=true` |
| Check a cell without a call id (server restarted, or an old call) | `verify_workbook` with `checks=[{cell, tool, args, key}]` |
| Korean statutory return forms (법정서식, 별지 서식) in Excel — filing forms with fixed box numbers and wording; not needed for a general workings workbook | `export_workbook` with `calls` |
| Optional, when a standard-layout workings file is wanted: Summary, Inputs with sources, side-by-side scenarios, Issues Log, own tables, one Calc detail sheet | `export_workbook` with `scenarios`, `sources`, `issues`, `actions`, `key_figures`, `extra_sheets`, `detail` |
| Tax memo or opinion as a Word document (.docx) — not built here | korean-tax-mcp `tax_memo_guide`, then `build_tax_memo` |
| Check sheet or statutory-form workbook in English for foreign readers (labels as "English (Korean)", statutory basis as English citations such as "Corporate Tax Act (법인세법) Art. 98(1)6") | `verify_workbook` with `lang="en"` for a workbook you built yourself; `export_workbook` with `lang="en"` |
| Give English (or other wording) to labels left in Korean — re-saving the file drops the stored values (phones show 0); if it was re-saved, `verify_workbook` fills them back in | `export_workbook` with `labels={"원래 라벨": "text"}` |

The table lists the main tools; `find_tool` searches all 140.

Example (invented figures) — a dividend reported at 15% where 20% applies. Call the calculator once per scenario, write the workbook yourself, then check it by call id.

```
nonresident_withholding(income_kind="배당", recipient_type="법인", residence_country="프랑스", year=2025, amount=40000000, treaty_rate=0.15)   # result: 호출_id "c1"
nonresident_withholding(income_kind="배당", recipient_type="법인", residence_country="프랑스", year=2025, amount=40000000)                    # result: 호출_id "c2"
# ... build and save /path/Dividend_review.xlsx with your own layout ...
verify_workbook(path="/path/Dividend_review.xlsx", lang="en",
  checks=[{"cell": "Dividend!B6", "call": "c1"}, {"cell": "Dividend!C6", "call": "c2", "key": "원천징수세액"}])
```

## For foreign companies, expats and Korean subsidiaries

- Paying a foreign parent (royalties, interest, dividends, service fees): `nonresident_withholding`, `thin_capitalization`
- Foreign employees and expats in Korea: `foreign_worker_flat_tax`, `foreign_expert_income_reduction`, `wage_income_tax`
- Nonresidents with Korean assets: `nonresident_capital_gains_withholding`, `nonresident_inheritance_gift`; foreign companies with a Korean branch: `branch_profits_tax`
- Buying services from abroad: `vat_reverse_charge`
- Seconded staff: `expat_cost_recharge`; residency of the employee: korean-tax-mcp `residency_check`
- Korean parent of foreign subsidiaries: `foreign_subsidiary_dividend`, `foreign_tax_credit`, `cfc_deemed_dividend`, `overseas_subsidiary_statement`
- Intercompany pricing: `arm_length_range`, `international_transaction_statement`
- Worked examples (with korean-tax-mcp): [Use cases](https://upstageai.github.io/korean-tax-mcp/use-cases/)

## Companion servers

- [korean-tax-mcp](https://github.com/UpstageAI/korean-tax-mcp): finds the legal basis — statutes on any date, NTS rulings, court decisions, 96 tax treaties, treaty withholding rates, residency test, transfer pricing guides. `uvx korean-tax-mcp`
- [korean-report-hwpx](https://github.com/UpstageAI/korean-report-hwpx): Korean government-format reports and press releases (HWPX). `uvx korean-report-hwpx`

## Limits

- Not tax advice. Results are reference calculations; verify against the statute text (korean-tax-mcp `law_article` with `as_of`) and consult a qualified professional.
- Rates and limits follow per-year tables for 2016–2026 checked against the statutes and their addenda; each result states its statutory basis and the points that need a professional's check.
- Treaty rates are not built into `nonresident_withholding`; pass the rate you confirmed from the treaty.
- The server does not fetch exchange rates; you supply them.

## Docs

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