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

@appmonster/mcp-popbill

用于 Popbill（팝빌） 的 MCP 服务——这是一款接入 Hometax 的韩国电子文档平台。一个服务即可为 Agent 提供：

• 电子税务发票：搜索、读取、开具（一次调用即可保存、开具并向 NTS 申报）、取消
• Hometax 采集：拉取通过任何渠道开具的销售/采购发票（不限于通过 Popbill 开具），用于记账和增值税准备
• Kakao 通知톡：使用已批准模板发送官方 KakaoTalk 商务通知（支持 SMS 备用发送）

所有写入操作都会消耗 Popbill 积分，和/或触达国税厅或真实手机，因此在配置后，每个写入工具都会通过人工审批钩子（OK Agent）执行。

工具

工具	访问权限	功能
popbill_check_account	读取	查询会员状态和积分余额
popbill_search_taxinvoices	读取	搜索销售/采购税务发票（按期间、状态、文本）
popbill_get_taxinvoice	读取	获取税务发票详情和查看 URL
popbill_issue_taxinvoice	写入	正常开具并立即开具——根据明细自动计算供应价、税额和合计
popbill_cancel_taxinvoice	写入	取消开具（在发送至国税厅之前）
popbill_hometax_request	读取	请求 Hometax 采集任务 → jobId（需另行申请 Popbill Hometax 采集包月服务——测试集成密钥也默认不包含此服务）
popbill_hometax_results	读取	查询采集状态/结果（采集中 · 已完成 · 失败）
popbill_list_alimtalk_templates	读取	列出已批准模板（用于检查变量）
popbill_send_alimtalk	写入	发送通知톡（≤1,000 人，支持 SMS 备用发送）
popbill_get_alimtalk_result	读取	查询发送结果（按收件人）

设置

1. 前往 https://developers.popbill.com → 申请 API 集成 → 获取 LinkID / SecretKey（测试集成即时开通，正式环境需审核）。
2. 前往 https://www.popbill.com 以企业身份注册。开具税务发票需要注册共同认证书，Hometax 采集需要Hometax 认证书或注册部门用户，通知톡则需要Kakao 频道 + 模板审批 + 注册发件号码（均需在 Popbill 网站上一次性设置）。
3. MCP 客户端配置：

{
  "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（默认值）使用 Popbill 测试服务器——发票不会发送至 NTS，通知톡不会发送至手机，并且每个工具的描述都会标记 [TEST SERVER]。只有在启用审批钩子时，才将其切换为 false：

"OKAGENT_API_KEY": "ok_…"

如果未启用，写入工具也不会在未经确认的情况下直接运行：首次调用会返回预览和 confirm_token，只有在你于聊天中同意后，Agent 才会再次调用。配置 OK Agent 密钥（免费，每月 200 次）后，请求会改为发送到你的手机——你可以在 KakaoTalk 上审批，并留下日志。KMCP_WRITE_MODE=direct 会关闭检查，适用于你完全信任的脚本。

Popbill 默认会按 IP 限制 API 调用（POPBILL_IP_RESTRICT，默认开启——请在 팝빌 > 연동관리 中注册你的 IP，或在需要漫游的机器上设为 false）。

开具发票——Agent 发送的内容

{
  "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；发票已开具并通过电子邮件发送，且已返回 NTS 确认编号。可搭配 kr_check_business（公共数据服务）事先验证买方的号码。

备注

• 此软件包封装了官方 popbill Node SDK（转换为 Promise）；测试会注入模拟对象，不会发起网络请求。
• 通知톡内容在替换变量后必须与已批准模板逐字节一致——请先使用 popbill_list_alimtalk_templates 读取模板。
• Hometax 采集为异步操作：请求 → 轮询结果。采集 6 个月采购记录的任务通常不到一分钟即可完成。

开发

pnpm --filter @appmonster/mcp-popbill test