Korea Invoice MCP Server

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

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.