Gooodbilling MCP server

<!-- mcp-name: io.github.gooodbilling/mcp-server -->

@gooodbilling/mcp-server

GooodBilling 公式 MCP Server。Claude Desktop / Cursor 等の MCP 対応クライアントから、AI ファーストで請求書・見積書を操作できます。

「A 社向け Web 制作 30 万円で請求書作って」「保守費 10 万円も追加して」「これで送信して」— PC を開かず、チャットだけで業務を完結できます。

動作要件

• Node.js 18 以上
• GooodBilling アカウントと API トークン (発行手順は下記)

API トークンの発行

1. GooodBilling にログイン
2. 設定 > AI 連携 > API トークン を開く
3. 「新しいトークンを発行」をクリック
4. 用途別テンプレートから選択 (Claude Desktop 推奨スコープを選ぶと簡単)
5. 表示された平文トークン (gblive...) を 1 度だけコピー

⚠️ トークンは発行時に 1 度だけしか表示されません。必ずすぐに MCP クライアントの設定に登録してください。

Claude Desktop での設定

1. 設定ファイルを開く

• macOS: ~/Library/Application Support/Claude/claudedesktopconfig.json
• Windows: %APPDATA%\Claude\claudedesktopconfig.json

2. mcpServers セクションに以下を追加

{
  "mcpServers": {
    "gooodbilling": {
      "command": "npx",
      "args": ["-y", "@gooodbilling/mcp-server"],
      "env": {
        "GOOODBILLING_API_TOKEN": "gb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

3. Claude Desktop を再起動

ツールアイコンに gooodbilling が表示されれば成功です。

💡 AI への話しかけ方 (重要)

Claude / ChatGPT 等の AI は、あなたのチャットを 複数の MCP (Gmail / Calendar / Drive / Stripe など) や Web 検索 から拾える状態で受け取ります。「カナリア出版の連絡先教えて」とだけ言われると、AI は GooodBilling の取引先なのか実在出版社なのか判断できず、確認質問されるか Web 検索に流れます。

これを避けるため、セッション最初の 1 発目 だけ以下のヒント語を含めてください。2 発目以降は文脈が確立されるので省略 OK です。

単語の 3 段階

プレフィックス語の選択肢

どれか 1 つ含めれば OK:

• GooodBillingで / GooodBillingの
• 請求システムの / 請求管理の
• 取引先の / 顧客の / 売上先の
• AI 連携の (送信機能・設定の文脈)

良い例 / 悪い例

請求書 未払い 未回収 売掛金 見積 案件 のような Tier 1 語を含む場合はそのまま使えます:

• ✅ カナリア出版に 5 万円で請求書出して ← 請求書 で確定
• ✅ 未払いある？ ← 未払い で確定
• ✅ 未回収教えて ← 未回収 で確定
• ✅ カナリアの見積一覧見せて ← 見積 で確定

🔀 Stripe / 決済プロバイダ系 MCP を併用している場合

AI クライアントに Stripe など他の請求・決済 MCP が同時接続されていると、Tier 1 単語であっても AI 側がそちらを優先することがあります (「未払い」「請求書」等は Stripe のドメインにも存在するため)。

その環境では 最初の 1 発目に GooodBillingで を付けるのが最も確実:

対策の優先順:

1. ブランド名プレフィックス (最確実): GooodBillingで未払いある？
2. GooodBilling 固有用語: 売掛金の未回収どう？ / 請求書 (発行側) の未払い見せて
3. 文脈確立: 最初の 1 発に 適格請求書の発行状況 等の業務特化語を使う → 2 発目以降は省略可

📱 AI クライアント別の挙動メモ

提供ツール (16 個)

取引先

• searchcustomers** — 取引先を検索 (名前・カナ・メール・登録番号)

請求書

• listinvoices** — 請求書一覧 (status / customer / 期間フィルタ)
• listunpaidinvoices — 未入金請求書一覧 (overdue 限定可)
• getinvoice** — 請求書 1 件詳細
• createinvoicedraft — 請求書ドラフト作成 (必ず draft 状態)
• updateinvoicedraft — ドラフト部分更新 (items 配列全置換)
• discardinvoicedraft — ドラフト破棄 (draft 状態のみ)
• sendinvoice** — 取引先へメール送付 (idempotency-key 自動付与)

見積

• listquotes** — 見積一覧
• getquote** — 見積 1 件詳細
• createquotedraft — 見積ドラフト作成
• updatequotedraft — ドラフト部分更新
• discardquotedraft — ドラフト破棄
• sendquote** — 取引先へメール送付

レポート

Shortened. The full README is on GitHub.