K-MCP — the Korean toolkit for AI agents

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 under io.github.groove79/*.

Servers

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.

Related MCP server: mcp-dev-brasil

30-second install

One-click install (no keys needed):

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. Free for light use (100 calls/day per IP); a free key from okagent.kr raises it.

Claude Desktop one-click: download a .mcpb file from Releases and double-click it.

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

{
  "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:

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:

"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

• 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?

→ 서버 요청 이슈 열기 — 사람이든 AI 에이전트든 같은 폼을 씁니다.

• 평일 기준 24~48시간 안에 첫 버전(읽기 툴)을 npm에 올립니다. 쓰기 툴은 승인 훅과 함께 그 다음 버전에.

• 테스트 계정/키를 빌려주면 가장 빠르고, 문서 링크만 있어도 시작합니다. 실제 API로 매일 검사하는 카나리에 자동 편입됩니다.

• 요청이 들어오는 순서대로 로드맵에 반영합니다. 미리 조사해 둔 후보: 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

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

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

MIT © Appmonster — built by a solo developer who runs a Smart Store, exports solar lighting, and got tired of agents that stop at the Korean border.