Korea Invoice MCP 🇰🇷 — How can my AI agent issue a 전자세금계산서 (electronic tax invoice) in Korea?

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

{
  "mcpServers": {
    "korea-invoice": {
      "type": "http",
      "url": "https://inv-kr.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

git clone https://github.com/junter1989k-ai/korea-invoice-mcp && cd korea-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent issue, query and transmit Korean 전자세금계산서 (electronic tax invoices) through POPBiLL / Linkhub — Korea's national-scale e-tax-invoice ASP that issues the invoice to the buyer and reports it to 국세청 (NTS / National Tax Service). It mints a Linkhub session token (HMAC-SHA256) per request, computes 부가세 (VAT), issues in one step (registIssue / 즉시발행), and returns the 문서관리번호 and 국세청 승인번호. Stateless, bring-your-own credentials, never stores anything.

Pure BYO — we are not an authentication intermediary. You self-issue your own Linkhub LinkID + SecretKey (free at linkhub.co.kr, 파트너 신청, ~20 min), join popbill.co.kr (연동회원가입), and register your 공동인증서 (certificate) on your own POPBiLL account. This server never holds a LinkID and never issues invoices on a shared identity. See Why no ISV-managed mode.

Live endpoint: https://inv-kr.wishpool.app/mcp · Registry: app.wishpool/korea-invoice-mcp

Quick start

{
  "mcpServers": {
    "korea-invoice": {
      "type": "http",
      "url": "https://inv-kr.wishpool.app/mcp",
      "headers": {
        "x-popbill-linkid": "your-linkhub-linkid",
        "x-popbill-secretkey": "your-linkhub-secretkey",
        "x-popbill-corpnum": "1234567890",
        "x-popbill-mode": "prod"
      }
    }
  }
}

x-popbill-corpnum is your 10-digit 사업자번호 — the invoicer/seller; invoices are issued from this business. Omit x-popbill-mode to stay in POPBILL_TEST (no fiscal effect). Your keys and certificate stay with you — this server never stores them.

Getting your credentials (self-service, free)

1. Linkhub 파트너 신청 at linkhub.co.kr → you receive your own LinkID + SecretKey (issued in ~20 minutes).
2. POPBiLL 연동회원가입 at popbill.com with the same business.
3. Register your 공동인증서 (전자세금계산서용 인증서) on your POPBiLL account — required by the NTS to issue tax invoices. It stays on your account; it never passes through this server.

Tools

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them. The cap applies to the invoice total (KRW).

부가세 (VAT) — computed server-side

POPBiLL does not compute VAT; this server does, deterministically:

• 과세 (standard): per-line tax = floor(supplyCost × 0.10) — 원 단위 절사 (integer truncation).
• 영세 (zero-rated export) / 면세 (exempt): tax = 0.

Each line carries a NET unit_cost in whole won; the server sums supplyCostTotal, taxTotal and totalAmount and stringifies the amounts as POPBiLL expects.

How it works (POPBiLL / Linkhub flow)

1. Session token (HMAC-SHA256, per request, never cached): POST auth.linkhub.co.kr/{POPBILL|POPBILL_TEST}/Token with body {"access_id": "<사업자번호>", "scope": ["member", "110"]} (110 = 세금계산서 scope). The request is signed: signature = base64( HMAC_SHA256( base64_decode(SecretKey), "POST\n" + base64(sha256(body)) + "\n" + callDT + "\n2.0\n/{ServiceID}/Token" ) ), with headers x-lh-date, x-lh-version: 2.0, Authorization: LINKHUB {LinkID} {signature}. Returns session_token.
2. Issue: POST /Taxinvoice with header X-HTTP-Method-Override: ISSUE and the Taxinvoice JSON (forceIssue set for 즉시발행). Business host popbill-test.linkhub.co.kr (test) / popbill.linkhub.co.kr (prod), Authorization: Bearer {session_token}, x-pb-version: 1.0. Returns the 국세청 승인번호.
3. Transmit / status: POST /Taxinvoice/{MgtKeyType}/{MgtKey} (override NTS) forces transmission; GET /Taxinvoice/{MgtKeyType}/{MgtKey} reads the stateCode.

The token signing and forwarding happen in memory per-request; nothing is embedded or stored.

Why no ISV-managed mode

An ASP integrator could hold one master LinkID/SecretKey and issue invoices for many merchants on that shared identity (an "ISV-managed" or 대행 model). This server deliberately does not do that: it would make us an authentication intermediary holding other businesses' issuing power and, in Korea, the 공동인증서 that legally binds a 전자세금계산서. Pure BYO keeps issuing authority — and liability — entirely with the merchant, and keeps this server a stateless forwarder that stores nothing. It costs the merchant one free 20-minute signup; we think that is the right trade.

Scope & honest gaps

• Issue + query + force-transmit in v0.1. Cancelling/amending an issued invoice (수정세금계산서 / 발행취소) is a separate POPBiLL operation kept out of this version to stay focused. To correct a mistake, issue a 수정세금계산서 through your POPBiLL account.
• KRW only, whole-won integer amounts.
• NTS transmission timing: create_invoice issues to the buyer immediately and gets a 승인번호; the actual 국세청 전송 defaults to next-day (익일전송). send_to_nts forces it now. There is no way to make issuance itself skip the buyer — issuing is delivering to the buyer.
• No real-credential live issue was run here — see below.

Develop

node test/serve.js   # local server on :3244
node test/e2e.js     # protocol + validation + 부가세-math + HMAC-SHA256 test vectors + LIVE probes

The e2e suite asserts the Linkhub signature algorithm against a fixed test vector (fixed input → fixed HMAC-SHA256 base64), the VAT math (과세 floor / 영세 / 면세), and makes two real calls to the government-facing POPBiLL/Linkhub test infrastructure:

• Fake LinkID → auth.linkhub.co.kr/POPBILL_TEST/Token returns -99004021 ("링크아이디가 존재하지 않습니다.") — the auth endpoint is alive and the full HMAC signing path is exercised.
• Fake Bearer → popbill-test.linkhub.co.kr/Taxinvoice/SELL/... returns -99910004 ("Token decryption failed.") — the business endpoint is alive.

These are the deepest live proofs possible without a portal-minted LinkID and a registered 공동인증서.

Safety

Pure stateless translation layer to the POPBiLL / Linkhub API. Credentials travel per-request in headers; the session token is minted (HMAC-SHA256) and used in memory only, then discarded; the 공동인증서 stays on the merchant's own POPBiLL account. Nothing is stored or logged. Privacy policy.

Sister servers

National e-invoices: Mexico CFDI 4.0 inv-mx · Brazil NFS-e inv-br · Chile DTE inv-cl · Poland KSeF inv-pl · Hungary NAV inv-hu · Malaysia MyInvois inv-my. Korea payments (card / KakaoPay / NaverPay / 가상계좌 via Toss) mcp-kr · Shipping for AI agents logi-tw · Local payments in 81+ countries, one family: mcp.wishpool.app (Taiwan e-invoice 電子發票 included).

MIT licensed.