gooodbilling

@gooodbilling/mcp-server

GooodBilling 官方 MCP 服务。通过 Claude Desktop / Cursor 等支持 MCP 的客户端，即可通过 AI 优先的方式处理发票和报价单。

“给 A 公司做一张 30 万日元的网站制作发票”“再加上 10 万日元的维护费”“就这样发送”——无需打开电脑，只用聊天即可完成工作。

---

运行要求

• Node.js 18 或更高版本
• GooodBilling 账户和 API 令牌（签发步骤见下文）

签发 API 令牌

1. 登录 GooodBilling
2. 打开 设置 > AI 联动 > API 令牌
3. 点击“签发新令牌”
4. 从用途模板中选择（选择 Claude Desktop 推荐的权限范围即可轻松完成）
5. 复制显示的明文令牌（gb_live_...），仅此 1 次

⚠️ 令牌在签发时仅显示 1 次。请务必立即将其添加到 MCP 客户端的设置中。

在 Claude Desktop 中配置

1. 打开配置文件

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.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 等）或网络搜索中获取信息。如果你只说“告诉我金丝雀出版社的联系方式”，AI 无法判断这是 GooodBilling 中的客户，还是现实中的出版社，因此可能会向你提问确认，或转而进行网络搜索。

为了避免这种情况，请仅在会话开始时的第 1 条消息中加入以下提示词。第 2 条及之后的消息会基于已建立的上下文，无需再加。

单词的 3 个等级

等级	示例	是否需要前缀？
Tier 1：GooodBilling 专属词	发票 / 未付款 / 未收款 / 应收账款 / 报价 / 项目 / 账单	❌ 不需要（单独使用即可）
Tier 2：其他系统也会使用的词	联系方式 / 销售额 / 发送 / 设置 / 交易记录	✅ 需要
Tier 3：仅有专有名词	仅公司名（金丝雀出版社等）	✅ 需要

可选前缀

包含以下任意 1 个即可：

• GooodBillingで / GooodBillingの
• 請求システムの / 請求管理の
• 取引先の / 顧客の / 売上先の
• AI 連携の（用于发送功能或设置相关的上下文）

正面示例 / 反面示例

❌ 含糊（转而进行网络搜索 / 被要求确认）	✅ 确保调用
カナリア出版の連絡先教えて	取引先のカナリア出版の連絡先教えて
今月の売上どんなもん？	請求システムの今月の売上は？
送信機能 ON だっけ？	AI 連携の送信機能 ON だっけ？
あの会社の電話番号	顧客の○○社の電話番号

如果包含 請求書 未払い 未回収 売掛金 見積 案件 等 Tier 1 词语，则可以直接使用：

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

---

🔀 同时使用 Stripe / 支付服务商类 MCP 时

如果 AI 客户端同时连接了 Stripe 等其他账单或支付类 MCP，即使使用 Tier 1 词语，AI 也可能优先选择其他 MCP（“未付款”“发票”等词语也属于 Stripe 的领域）。

在这种情况下，最稳妥的做法是在第 1 条消息中加上 GooodBillingで：

短语	可能出现的行为（同时使用 Stripe 时）
未払いある？	可能优先选择 Stripe
売上どう？	查看 Stripe Payments 的销售额
請求書一覧	有时会优先选择 Stripe Invoices

建议优先采取以下措施：

1. 品牌名作为前缀（最稳妥）：GooodBillingで未払いある？
2. 使用 GooodBilling 专属词语：売掛金の未回収どう？ / 請求書 (発行側) の未払い見せて
3. 建立上下文：在第 1 条消息中使用 適格請求書の発行状況 等业务专用词语 → 第 2 条及之后的消息可省略

---

📱 不同 AI 客户端的行为说明

客户端	前缀	备注
Claude Desktop / Cursor	（上述规则）	建议将工具权限设为“始终允许”
ChatGPT (Custom GPTs Actions)	不需要	通过 OpenAPI 仅调用 1 个 API，因此没有歧义
LINE / Slack Bot	不需要	Bot 的实现方式是仅调用 GooodBilling API
Zapier / Make / n8n	不需要	通过触发器/操作明确指定 API。建议尽量缩小权限范围

---

提供的工具（16 个）

客户

• search_customers — 搜索客户（名称、假名、邮箱、注册编号）

发票

• list_invoices — 发票列表（按 status / customer / 时间段筛选）
• list_unpaid_invoices — 未收款发票列表（可仅显示 overdue）
• get_invoice — 获取单张发票的详细信息
• create_invoice_draft — 创建发票草稿（状态始终为 draft）
• update_invoice_draft — 部分更新草稿（完整替换 items 数组）
• discard_invoice_draft — 丢弃草稿（仅限 draft 状态）
• send_invoice — 通过邮件发送给客户（自动添加 idempotency-key）

报价单

• list_quotes — 报价单列表
• get_quote — 获取单张报价单的详细信息
• create_quote_draft — 创建报价单草稿
• update_quote_draft — 部分更新草稿
• discard_quote_draft — 丢弃草稿
• send_quote — 通过邮件发送给客户

报告

• get_sales_summary — 时间段汇总（账单金额、收款金额、未收款金额）

租户设置

• get_tenant_settings — 查看发送功能的开/关状态、自动添加 BCC、默认税率（只读）

---

“创建 → 确认 → 发送”两阶段流程（对话示例）

👤 ユーザー
「A社向けに、Web制作費 30万円で請求書ドラフトを作って」

🤖 Claude
search_customers({query: "A社"}) → cus_xxx (株式会社サンプルA)
create_invoice_draft({customer_id: "cus_xxx", title: "Web 制作費", ...})
→ { id: "inv_yyy", status: "draft", total_amount: 330000, pdf_preview_url: "..." }

「下書きを作成しました。
 取引先: 株式会社サンプルA
 合計: ¥330,000 (税込)
 [PDF を確認する](pdf_preview_url)
 内容に問題なければ『送信して』とお伝えください。」

👤 ユーザー
「保守費 10万円も追加して」

🤖 Claude
get_invoice({invoice_id: "inv_yyy"}) → 現状取得
update_invoice_draft({invoice_id: "inv_yyy", items: [Web制作費, 保守費]})
→ total_amount: 440000

「修正しました。保守費 10万円を追加し、合計 ¥440,000 になりました。
 [更新後の PDF を確認](pdf_preview_url)」

👤 ユーザー
「OK、送信して」

🤖 Claude
send_invoice({invoice_id: "inv_yyy"}) → status: "sent"

「A社の担当者様 ([email protected]) へ送付完了しました。
 控えがあなたのメールにも届きます。」

---

面向 AI Agent 实现者的最佳实践

本节面向将 MCP Server 集成到应用程序（LINE Bot、Slack Bot、语音助手等）中的实现者，介绍 AI 模型在构造工具调用时应遵循的原则。

1. 确认交易对象：不要捏造虚构 ID

传给 create_invoice_draft / create_quote_draft 的 customer_id，必须使用通过 search_customers 获取的真实 ID。如果 AI 凭记忆或猜测拼凑 UUID，将会返回 422 invalid_request。

如果搜索结果为 0 条，请勿擅自登记新交易对象，而应请用户确认正式名称。

2. 税率：建议不指定

建议省略 items[].tax_rate_code。服务器会按以下优先级自动补全：

1. 商品主数据中的默认税率（description 匹配时）
2. 交易对象主数据中的默认税率
3. 租户默认税率
4. 标准 10% (STD10)

这样可以从机制上避免 AI 幻觉导致擅自套用减轻税率的情况。如需指定，请传入已登记在租户税率主数据中的代码（例如：STD10、RED8）。

3. 修改前先了解当前状态

调用 update_invoice_draft / update_quote_draft 前，务必先通过 get_invoice / get_quote 获取最新状态，在内存中合并 items[] 后再执行 PATCH。

包含 items[] 的 PATCH 会整体替换数组，因此如果不进行合并，现有明细将会丢失。

4. 发送前必须审核

send_invoice / send_quote 会向交易对象发送邮件，且无法撤回。

调用前务必向用户展示 pdf_preview_url，并取得明确同意（例如“发送”“OK”）。请避免 AI 单方面决定发送。

5. 幂等键的处理

发送类工具可以省略 idempotency_key。MCP Server 会自动生成并附加 UUID。

对于同一发送意图（例如用户连续两次输入“发送”），传入相同的 idempotency_key 可从机制上防止重复发送。

6. 作废范围

discard_invoice_draft / discard_quote_draft 只能作废 draft 状态的单据。

对于已确认（issued / sent / paid）的单据，不要通过 API 取消，并请告知用户“需要在 Web 界面中进行红字处理”。

---

环境变量

变量	必需	默认值	说明
GOOODBILLING_API_TOKEN	✅	—	API 令牌 (gb_live_...)
GOOODBILLING_API_BASE_URL	❌	https://gooodbilling.com	API 基础 URL（用于可自托管 / staging）

---

故障排除

启动失败，提示 FATAL: GOOODBILLING_API_TOKEN is not set

→ 请确认令牌已正确设置在 MCP 客户端配置的 env 部分中。

返回 401 invalid_token

→ 令牌可能已失效或过期。请在管理界面中重新签发。

返回 403 insufficient_scope

→ 令牌未获授所需权限范围（例如：send_invoice 需要 emails:send + invoices:write）。请在管理界面中检查权限范围；如有缺失，请重新签发令牌。

返回 403 send_disabled_by_tenant

→ 租户管理员已暂时停用“通过 AI / API 发送”。请在管理界面中通过 设置 > AI 连接 > API 令牌 > 发送设置 启用。

返回 422 customer_email_missing

→ 交易对象的联系人未登记电子邮件地址。请在 Web 界面中为交易对象联系人设置电子邮件，或通过 send_invoice 的 to 参数明确指定。

---

许可证

MIT