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

@appmonster/mcp-popbill

Popbill（팝빌） 用 MCP サーバーです。Hometax の窓口となる韓国の電子文書プラットフォームです。このサーバーを使うと、エージェントは次の操作を行えます。

• 電子税金計算書：検索、取得、発行（保存・発行・NTS への申告を 1 回の呼び出しで実行）、取消
• Hometax 収集：Popbill 経由で発行されたものだけでなく、あらゆる場所で発行された売上・仕入の税金計算書を、記帳や VAT の準備のために取得
• カカオ通知トーク：承認済みテンプレートを使った公式の 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	読み取り	収集の状態／結果（collecting · done · failed）
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 認証書または部門ユーザーの登録、通知トークにはカカオチャンネル＋テンプレートの承認＋発信者番号の登録がそれぞれ必要です（Popbill のサイトで 1 回行います）。
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 が返され、チャットであなたが同意した後に限り、エージェントが再度呼び出します。OK Agent のキー（無料、月 200 回まで）があれば、代わりにリクエストがあなたの電話に届きます。KakaoTalk で承認でき、ログも残ります。KMCP_WRITE_MODE=direct を指定すると、完全に信頼できるスクリプト向けに確認を無効にできます。

Popbill はデフォルトで API 呼び出しを IP アドレスで制限します（POPBILL_IP_RESTRICT のデフォルトは有効 — 팝빌 > 연동관리 で IP アドレスを登録するか、移動するマシンでは false に設定してください）。

税金計算書の発行 — エージェントが送信する内容

{
  "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 か月分の仕入のジョブは 1 分以内に完了します。

開発

pnpm --filter @appmonster/mcp-popbill test