Popbill (세금계산서·알림톡)

@appmonster/mcp-popbill

MCP server for Popbill (팝빌) — the Korean e-document platform that fronts Hometax. One server gives an agent:

• 전자세금계산서: search, read, issue (saved + issued + reported to the NTS in one call), cancel
• 홈택스 수집: pull sales/purchase invoices issued anywhere (not only via Popbill) for bookkeeping and VAT prep
• 카카오 알림톡: official KakaoTalk business notifications with approved templates (SMS fallback)

All writes cost Popbill points and/or reach the 국세청 or real phones, so every write tool runs through the human approval hook (OK Agent) when configured.

Tools

Setup

1. https://developers.popbill.com → API 연동 신청 → LinkID / SecretKey (test 연동은 즉시, 운영은 심사).
2. https://www.popbill.com 에서 사업자로 가입. 세금계산서 발행은 공동인증서 등록, 홈택스 수집은 홈택스 인증서 또는 부서사용자 등록, 알림톡은 카카오 채널 + 템플릿 승인 + 발신번호 등록이 각각 필요합니다 (팝빌 사이트에서 1회).
3. MCP client config:

{  "mcpServers": {    "popbill": {      "command": "npx",      "args": ["-y", "@appmonster/mcp-popbill"],      "env": {        "POPBILL_LINK_ID": "…",        "POPBILL_SECRET_KEY": "…",        "POPBILL_CORP_NUM": "1234567890",        "POPBILL_USER_ID": "myid",        "POPBILL_TEST": "true"      }    }  }}

POPBILL_TEST=true(default) uses Popbill's test server — invoices never reach the NTS, 알림톡 never reaches phones, and every tool description is tagged [TEST SERVER]. Switch to false only with the approval hook on:

"OKAGENT_API_KEY": "ok_…"

Without it, write tools still never run blind: the first call returns a preview and a confirm_token, and the agent re-calls only after you agree in the chat. With an OK Agent key (free, 200/month) the request goes to your phone instead — approve on KakaoTalk, with a log. KMCP_WRITE_MODE=direct turns the check off for scripts you fully trust.

Popbill restricts API calls by IP by default (POPBILL_IP_RESTRICT, default on — register your IP in 팝빌 > 연동관리, or set false for roaming machines).

Issuing an invoice — what the agent sends

{  "mgtKey": "INV-20261021-001",  "writeDate": "20261021",  "invoicer": { "corpNum": "123-45-67890", "corpName": "앱몬스터", "ceoName": "윤유성", "email": "[email protected]" },  "invoicee": { "corpNum": "987-65-43210", "corpName": "거래처", "ceoName": "김대표", "email": "[email protected]" },  "items": [{ "name": "앱 개발", "supplyCost": 3000000 }]}

→ 공급가액 3,000,000 / 세액 300,000 / 합계 3,300,000, issued, emailed, NTS confirmation number returned. Pair with kr_check_business (public-data server) to verify the buyer's number first.

Notes

• This package wraps the official popbill Node SDK (promise-ified); tests inject fakes, no network.
• 알림톡 content must match the approved template byte-for-byte after variable substitution — read it with popbill_list_alimtalk_templates first.
• Hometax collection is async: request → poll results. A job for 6 months of purchases typically finishes in under a minute.

Development

pnpm --filter @appmonster/mcp-popbill test