# Quokka Korea Tools

> Remote MCP server and HTTP API with exact tools for South Korean data: public holidays and business days, won amounts in Korean words, business registration number check digits, 만 나이, and phone/address/name normalization and PII masking. Free tier needs no key.
> 한국 공휴일·대체공휴일·영업일 계산, 숫자 한글 금액 변환, 사업자등록번호 검증, 만 나이 계산을 하는 원격 MCP 서버와 API.

MCP endpoint (Streamable HTTP, stateless): https://mcp.thequokkacompany.com/korea
HTTP API: POST https://mcp.thequokkacompany.com/api/korea/<tool_name> with a JSON body of arguments.
Dates are YYYY-MM-DD and default to today in Korea (KST, UTC+9). Holiday data covers 2024-2027 (source: KASI; updated 2026-11-12). It includes substitute holidays and election days, and the 2026 additions Labor Day (May 1) and Constitution Day (Jul 17). Other years return an error.
Free tier: 200 calls per day per client. Errors come back as {"error": "..."} (HTTP API) or isError results (MCP).

## Docs

- [Home](https://mcp.thequokkacompany.com/): setup for Claude Code, Claude.ai, Cursor, VS Code
- [한국어 안내](https://mcp.thequokkacompany.com/ko): 설정 방법과 도구 목록
- [OpenAPI](https://mcp.thequokkacompany.com/openapi.json): HTTP API schema for every tool
- [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=com.thequokkacompany/korea-tools): com.thequokkacompany/korea-tools

## Tools

- kr_holidays: List South Korean public holidays (공휴일) for a year or a date range, with Korean names.
- kr_business_day: Check whether a date is a business day in South Korea (not a weekend and not a public holiday), and give the previous and next business days.
- kr_add_business_days: Move forward (or back, with negative days) a number of South Korean business days from a start date, skipping weekends and public holidays. The start date itself is not counted. Use for deadlines like "within 7 business days".
- kr_count_business_days: Count South Korean business days between two dates (both ends included by default). Also returns weekend and weekday-holiday counts.
- kr_amount_to_korean: Write a won amount in Korean words exactly: reading form ("백이십삼만 사천오백육십칠 원", spaced every 만 per Korean orthography), contract/receipt form ("일금 일백이십삼만사천오백육십칠원정"), and mixed form ("123만 4,567원"). Whole numbers below 10^20.
- kr_korean_to_amount: Read a Korean money expression as an exact number: "1억 2천만 원", "삼백오십만원", "일금 일백만원정", "2.5억", "12만3천". Returns digits and comma form.
- kr_business_number_check: Validate the format and check digit of South Korean business registration numbers (사업자등록번호, 10 digits, NTS weights 1,3,7,1,3,7,1,3,5) and format them as 123-45-67890. This is an offline checksum test only: it does not tell whether the business is open or closed.
- kr_age: Compute international age (만 나이, the legal standard in Korea since June 2023) and year age (연 나이, used by the Youth Protection Act and military service) on a reference date. Input a birth date, or the first 7 digits of a resident registration number (YYMMDD-G) to also get sex and century. Feb 29 birthdays turn a year older on Mar 1 in common years. The input is not stored.
- kr_phone_format: Normalize South Korean phone numbers (mobile 010, Seoul 02, regional 031-064, 070, 050x safe numbers, 15xx/16xx/18xx company numbers) to one style. Restores a leading 0 dropped by Excel, converts +82, keeps extensions. Unknown shapes return null.
- kr_address_split: Split South Korean addresses into province/city (시도, normalized to the official name such as 서울특별시), district (시군구, including 일반구 like 수원시 영통구), base address (road name + building number) and detail (unit). Handles leading postal codes and addresses written without spaces. Rule-based; does not look up a database.
- kr_name_split: Split Korean full names into family name and given name, recognizing two-character surnames (남궁, 황보, 제갈, 선우 …). Flags names that are ambiguous from the characters alone (선우진 = 선 + 우진 or 선우 + 진). Latin-script names use the last word as family name.
- kr_mask_pii: Mask Korean personal data before you store, log or share it. Text mode finds and masks resident registration numbers (900101-1******), phone numbers (010-****-5678), emails (ab****@x.com) and 16-digit card numbers inside free text. Item mode masks given values by kind, including names (홍*동). Nothing is stored or logged.

## Examples

- POST https://mcp.thequokkacompany.com/api/korea/kr_business_day {"date":"2026-05-01"} → is_business_day false, holidays ["노동절"]
- POST https://mcp.thequokkacompany.com/api/korea/kr_add_business_days {"start":"2026-09-23","days":3} → 2026-09-30, skips 추석 (Sep 24-26) and Sunday
- POST https://mcp.thequokkacompany.com/api/korea/kr_amount_to_korean {"amount":"1234567"} → formal "일금 일백이십삼만사천오백육십칠원정"
- POST https://mcp.thequokkacompany.com/api/korea/kr_korean_to_amount {"text":"1억 2천만 원"} → 120000000