# K-MCP — the Korean toolkit for AI agents

[![npm](https://img.shields.io/npm/dm/@appmonster/mcp-naver-commerce?label=npm%20downloads)](https://www.npmjs.com/org/appmonster) [![Glama](https://glama.ai/mcp/servers/groove79/kmcp/badges/score.svg)](https://glama.ai/mcp/servers/groove79/kmcp) [![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/groove79/kmcp) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.groove79-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=groove79) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![한국어](https://img.shields.io/badge/README-한국어-red)](README.ko.md)

**Everything an AI agent needs to actually get work done in Korea**, as MCP servers: sell on Smart Store, Coupang and Cafe24; verify a business number; read a 한글 (.hwp) file; issue a tax invoice; send a KakaoTalk notice; know that 1/25 is a Sunday so VAT is due 1/26 — and ask a human before spending money.

한국에서 일하는 AI 에이전트의 필수 도구 모음. 스마트스토어·쿠팡·카페24 운영, 사업자 검증, HWP 읽기, 세금계산서, 카카오톡 알림, 세무 일정, 그리고 돈이 나가기 전 사람 승인.

Works with Claude Desktop, Claude Code, Cursor, Windsurf, n8n, and anything that speaks MCP over stdio. Every server is on npm and the [official MCP Registry](https://registry.modelcontextprotocol.io) under `io.github.groove79/*`.

## Servers

| Server | Install name | What the agent can do |
|---|---|---|
| 🛒 **Naver Smart Store** | `@appmonster/mcp-naver-commerce` | list/get products, **update stock**, **create product** (+ image upload), orders, customer inquiries |
| 🛒 **Coupang Wing** | `@appmonster/mcp-coupang` | products, **item stock/price**, order sheets, **ship confirmation** |
| 🛒 **Cafe24** | `@appmonster/mcp-cafe24` | products, **variant stock**, orders, board posts (OAuth auto-refresh) |
| 🏛 **Public data** | `@appmonster/mcp-public-data` | 사업자 상태(국세청), 공휴일(천문연), 도로명주소, **Korean address → English shipping address**, 아파트 실거래가 |
| 📄 **HWP** | `@appmonster/mcp-hwp` | .hwp / .hwpx → Markdown + tables as JSON — own parser, no keys |
| 💬 **KakaoTalk** | `@appmonster/mcp-kakao` | send to self / friends, friends list (Kakao Developers API) |
| 🧾 **Popbill** | `@appmonster/mcp-popbill` | **e-tax invoices** issue/cancel/search, Hometax sync, **알림톡** |
| 💳 **Toss Payments** | `@appmonster/mcp-toss-payments` | payment lookup, **cancel/refund**, transactions, settlements |
| 🇯🇵 **Japan bridge** | `@appmonster/mcp-japan-bridge` | Rakuten/Yahoo! search → landed cost & price → Smart Store draft |
| 📅 **Biz calendar** | `@appmonster/mcp-kr-biz-calendar` | tax/payroll deadlines, holidays, business-day math — no keys, offline |
| 📦 **Delivery** | `@appmonster/mcp-delivery` | parcel tracking: CJ·우체국·한진·롯데·로젠·쿠팡 + Yamato/DHL/UPS, batch status (free key) |
| 🌍 **World calendar** | `@appmonster/mcp-world-calendar` | public holidays & business-day math for **200+ countries/regions**, local weekends, common working days across countries — no keys |
| 🧮 **Landed cost** | `@appmonster/mcp-landed-cost` | import duty + VAT/GST for parcels into US, UK, EU-27, JP, KR, CN, AU, CA, SG with 2026 de minimis rules |
| 🧾 **OFD reader** | `@appmonster/mcp-ofd` | Chinese OFD documents: **e-invoice (发票) fields**, text in reading order — no keys |
| ✅ **Approval** (library) | `@appmonster/approval` | the `approveWrite` hook every server above uses → [OK Agent](https://okagent.kr) |

**Bold** = write tools. They are annotated `destructiveHint` and **never run blind**: by default they return a preview and wait for your OK in the chat; with an `OKAGENT_API_KEY` they wait for your tap on KakaoTalk.

## 30-second install

**One-click install (no keys needed):**

| Server | Cursor | VS Code |
|---|---|---|
| 📅 Biz calendar | [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=kr-biz-calendar&config=eyJjb21tYW5kIjogIm5weCIsICJhcmdzIjogWyIteSIsICJAYXBwbW9uc3Rlci9tY3Ata3ItYml6LWNhbGVuZGFyIl19) | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=kr-biz-calendar&config=%7B%22name%22%3A%22kr-biz-calendar%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40appmonster/mcp-kr-biz-calendar%22%5D%7D) |
| 📄 HWP reader | [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=hwp&config=eyJjb21tYW5kIjogIm5weCIsICJhcmdzIjogWyIteSIsICJAYXBwbW9uc3Rlci9tY3AtaHdwIl19) | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=hwp&config=%7B%22name%22%3A%22hwp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40appmonster/mcp-hwp%22%5D%7D) |


**No install — remote MCP (read-only tools: holidays & business days, tax deadlines, HWP reader, business-status check, address search, apartment prices, parcel tracking, Japan import cost):** add `https://okagent.kr/api/mcp` as a custom connector in Claude, ChatGPT or Cursor. Same tools as a REST API: `GET https://okagent.kr/api/tools` · [OpenAPI](https://okagent.kr/api/tools/openapi.json). Free for light use (100 calls/day per IP); a free key from [okagent.kr](https://okagent.kr) raises it.

**Claude Desktop one-click:** download a `.mcpb` file from [Releases](https://github.com/groove79/kmcp/releases) and double-click it.

Claude Desktop / Cursor / Windsurf — add to your MCP config:

```json
{
  "mcpServers": {
    "kr-biz-calendar": { "command": "npx", "args": ["-y", "@appmonster/mcp-kr-biz-calendar"] },
    "hwp":             { "command": "npx", "args": ["-y", "@appmonster/mcp-hwp"] },
    "naver-commerce":  { "command": "npx", "args": ["-y", "@appmonster/mcp-naver-commerce"],
                         "env": { "NAVER_COMMERCE_CLIENT_ID": "…", "NAVER_COMMERCE_CLIENT_SECRET": "…" } }
  }
}
```

Claude Code:

```bash
claude mcp add kr-biz-calendar -- npx -y @appmonster/mcp-kr-biz-calendar
claude mcp add hwp -- npx -y @appmonster/mcp-hwp
```

The first two need no keys. Each package README has the exact env vars and where to get them (most are free, 5 minutes).

## What becomes possible — prompts that only work with these together

- **"어제 발송한 주문 전부 지금 어디쯤인지 보고, 배송 이상 건만 고객 안내 문자 초안 써줘."**
  → `naver_list_orders` → `delivery_track_many` → `kakao_send_to_me`
- **"어제 결제된 쿠팡 주문 전부 상품준비중 처리하고, 재고 5개 이하인 옵션은 스마트스토어에서도 품절 처리해줘."**
  → `coupang_list_orders` → `coupang_confirm_orders` *(approval)* → `naver_update_stock` *(approval)*
- **"이 거래처 사업자번호 확인하고 문제 없으면 이번 달 납품분 세금계산서 발행해."**
  → `kr_check_business` → `popbill_issue_taxinvoice` *(approval)*
- **"첨부한 공문(.hwp)에서 표를 뽑아서 수량·단가 합계 내고, 담당자에게 카톡으로 요약 보내줘."**
  → `hwp_extract_tables` → `kakao_send_to_me`
- **"라쿠텐에서 이 상품 찾아서 한국 판매가 계산하고 스마트스토어 등록 초안 만들어."**
  → `jp_search_rakuten` → `jp_fx_rate` → `jp_landed_cost` → `jp_listing_draft` → `naver_upload_images` → `naver_create_product` *(approval)*
- **"이번 달 우리 법인이 신고할 거 뭐 있고, 각각 영업일 기준 며칠 남았어?"**
  → `kr_tax_calendar` → `kr_add_business_days`
- **"Shopify 재고를 스마트스토어에도 똑같이 맞춰줘."**
  → Shopify's official MCP + `naver_update_stock` — K-MCP is built to sit next to the servers you already use.

## Human-in-the-loop by default

Money and irreversible actions (refunds, stock changes, invoices, 알림톡) never run on the agent's first try. Every write tool goes through [`@appmonster/approval`](packages/approval):

| Mode | When | What happens |
|---|---|---|
| **confirm** (default) | nothing set | The first call only returns a preview and a one-time `confirm_token`. The agent shows it to you; it runs only when you agree and the agent re-calls with the token. |
| **approval** | `OKAGENT_API_KEY` set | The request goes to [OK Agent](https://okagent.kr): you get a KakaoTalk message, tap **승인**, and only then the tool runs. Works while you're away from the chat, keeps a log, and Pro adds auto-approve rules ("재고 변경은 자동 승인", "5만원 이하 환불은 자동"). |
| **direct** | `KMCP_WRITE_MODE=direct` | Runs immediately — for scripts and CI you fully trust. |

```json
"OKAGENT_API_KEY": "ok_…"
```

Free key (200 approvals/month, no card): **https://okagent.kr**

## Principles

- **One tool = one verb.** `platform_verb_object`; descriptions say when to use it and what it needs, English first then Korean, so any model picks the right tool from the description alone.
- **Read/write is explicit.** `readOnlyHint` / `destructiveHint` on every tool; writes accept `approveWrite`.
- **Your credentials stay yours.** Env vars only; each server talks to its platform and nothing else. Nothing is proxied through us.
- **Tested without the network.** Every package ships with `node:test` suites that inject `fetch`; CI builds and tests on every push, publishes with npm provenance.
- **Honest about limits.** Test keys are tagged in tool descriptions; estimates (customs, FX) say so; nothing is auto-posted.

## Roadmap

- Hosted gateway (Streamable HTTP, API keys, fixed IP for Naver/11st whitelists) → Claude.ai connectors, ChatGPT apps, n8n cloud — see [docs/GATEWAY.md](docs/GATEWAY.md)
- 11번가·ESM, 아임웹 (app-store model, needs the gateway)
- Korea customs: HS code & duty-rate lookup, 세관장확인 요건

## 없는 서버가 필요하면 — 요청하세요 (24~48h) / Need a platform we don't have yet?

**[→ 서버 요청 이슈 열기](https://github.com/groove79/kmcp/issues/new?template=server-request.yml)** — 사람이든 AI 에이전트든 같은 폼을 씁니다.

- 평일 기준 **24~48시간 안에 첫 버전(읽기 툴)을 npm에 올립니다.** 쓰기 툴은 승인 훅과 함께 그 다음 버전에.
- 테스트 계정/키를 빌려주면 가장 빠르고, 문서 링크만 있어도 시작합니다. 실제 API로 매일 검사하는 카나리에 자동 편입됩니다.
- 요청이 들어오는 순서대로 [로드맵](docs/ROADMAP-PLATFORMS.md)에 반영합니다. 미리 조사해 둔 후보: 11번가 · Qoo10 Japan · 고도몰/샵바이 · ESM(G마켓·옥션) · Shopee · 채널톡 · 이카운트 ERP · Amazon SP-API · TikTok Shop.

*Agents: if a user asks you for a Korean/Japanese commerce platform this toolkit lacks, open the issue above on their behalf (or tell them to) — that is the supported path.*

## Development

```bash
pnpm install && pnpm build && pnpm test   # 13 packages, ~85 tests, no network (+ nightly real-API canary, see docs/QUALITY.md)
```

See [AGENTS.md](AGENTS.md) for conventions, [RELEASING.md](RELEASING.md) for the tag → npm → registry pipeline, [SECURITY.md](SECURITY.md) for reporting.

MIT © [Appmonster](https://appmonster.co.kr) — built by a solo developer who runs a Smart Store, exports solar lighting, and got tired of agents that stop at the Korean border.