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

<!-- install-cta -->
## Use it in 60 seconds

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

```json
{
  "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](https://mcp.wishpool.app/trust).

### 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:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/junter1989k-ai/korea-invoice-mcp)

```bash
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](https://www.linkhub.co.kr), 파트너 신청, ~20 min), join [popbill.co.kr](https://www.popbill.com) (연동회원가입), 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](#why-no-isv-managed-mode).

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

## Quick start

```json
{
  "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](https://www.linkhub.co.kr) → you receive your own `LinkID` + `SecretKey` (issued in ~20 minutes).
2. **POPBiLL 연동회원가입** at [popbill.com](https://www.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

| Tool | What it does |
|---|---|
| `create_invoice` | Issue a 전자세금계산서 in one step (`registIssue` = 즉시발행) — `invoicer_corp_name`, `invoicer_ceo_name`, `invoicee_corp_name` (+ `invoicee_corp_num` for 사업자 buyers), `items` (`item_name`, `qty`, `unit_cost` KRW/NET), `tax_type` (과세/영세/면세), `purpose_type` (영수/청구) in; **mgt_key + ntsConfirmNum** out. The seller 사업자번호 comes from the header; **부가세 is computed for you**. `mgt_key` auto-generated if omitted. |
| `query_invoice` | Look up one invoice by `mgt_key` + `mgt_key_type` (SELL default / BUY / TRUSTEE) — returns the `stateCode` (200 발행완료, 300 국세청 전송대기, 320 국세청 전송완료, 330 전송실패, 400 발행취소), `ntsConfirmNum`, timestamps and totals. |
| `send_to_nts` | **Force immediate** 국세청 (NTS) transmission of an already-issued invoice. Normally transmission is automatic the **next day** (익일전송); this only sends it now instead of waiting for the batch. |

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

```bash
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](https://inv-kr.wishpool.app/privacy).

## Sister servers

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

MIT licensed.