Billingserv

BillingServ MCP 服务

B​​illingServ MCP 服务 可将 Claude、ChatGPT (Codex)、Cursor 和 Gemini 等 AI 助手连接到你的 BillingServ 账户。

它通过 Model Context Protocol (MCP) 提供对 BillingServ API 的访问。完成设置后，你的 AI 助手便可直接从 BillingServ 安装中查询客户、发票、订单、套餐、软件许可证和报告。你可以这样提问：

• “本月哪些客户有未付款的发票？”
• “显示今年的收入趋势。”
• “客户 123 有哪些套餐？可以升级到哪些套餐？”
• “验证此软件许可证的激活状态。”

助手会根据实时账单数据作答，而不是猜测。

你也可以让它执行操作：提交支持工单、创建订单、拟定发票，或为客户添加备注。

安全设计。 此服务只会调用固定允许列表中的 BillingServ 端点，并会在每次请求时进行检查。读取和写入操作使用不同的工具，因此你可以允许 AI 自由查询，同时要求其在创建或更改记录前先获得批准。此服务刻意不提供删除记录和收款功能。

要求

• Node.js 20 或更高版本（自带 npx）
• BillingServ API 密钥

配置

以下各客户端的设置都使用相同的三个环境变量：

变量	必填	描述
BILLINGSERV_API_BASE_URL	是	BillingServ API v2 基础 URL，例如 https://billing.example.com/api/v2
BILLINGSERV_API_KEY	是	BillingServ API 密钥
BILLINGSERV_TIMEOUT_MS	否	请求超时时间，单位为毫秒（默认值为 15000）

设置

找到你的客户端，填入 URL 和 API 密钥即可完成设置。

Claude Code

只需运行一条命令：

claude mcp add billingserv \
  --env BILLINGSERV_API_BASE_URL="https://billing.example.com/api/v2" \
  --env BILLINGSERV_API_KEY="your_api_key" \
  -- npx -y @billingserv/mcp-server

重启 Claude Code，然后尝试让它列出你的 BillingServ 端点。

Claude Desktop

打开 Settings → Developer → Edit Config，并将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "billingserv": {
      "command": "npx",
      "args": ["-y", "@billingserv/mcp-server"],
      "env": {
        "BILLINGSERV_API_BASE_URL": "https://billing.example.com/api/v2",
        "BILLINGSERV_API_KEY": "your_api_key"
      }
    }
  }
}

重启 Claude Desktop，然后在工具图标下查找 billingserv 工具。

OpenAI Codex CLI

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.billingserv]
command = "npx"
args = ["-y", "@billingserv/mcp-server"]

[mcp_servers.billingserv.env]
BILLINGSERV_API_BASE_URL = "https://billing.example.com/api/v2"
BILLINGSERV_API_KEY = "your_api_key"

Cursor

将以下内容添加到 ~/.cursor/mcp.json（全局配置）或项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "billingserv": {
      "command": "npx",
      "args": ["-y", "@billingserv/mcp-server"],
      "env": {
        "BILLINGSERV_API_BASE_URL": "https://billing.example.com/api/v2",
        "BILLINGSERV_API_KEY": "your_api_key"
      }
    }
  }
}

VS Code (GitHub Copilot)

将以下内容添加到工作区的 .vscode/mcp.json：

{
  "servers": {
    "billingserv": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@billingserv/mcp-server"],
      "env": {
        "BILLINGSERV_API_BASE_URL": "https://billing.example.com/api/v2",
        "BILLINGSERV_API_KEY": "your_api_key"
      }
    }
  }
}

Gemini CLI

将以下内容添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "billingserv": {
      "command": "npx",
      "args": ["-y", "@billingserv/mcp-server"],
      "env": {
        "BILLINGSERV_API_BASE_URL": "https://billing.example.com/api/v2",
        "BILLINGSERV_API_KEY": "your_api_key"
      }
    }
  }
}

其他 MCP 客户端

任何支持 stdio 服务的 MCP 客户端都可以使用。将其指向：

• 命令： npx
• 参数： -y @billingserv/mcp-server
• 环境： 配置 中的变量

工具

此服务向你的助手提供三个工具：

billingserv_list_endpoints

列出此服务可以调用的所有 BillingServ 端点，以及对应的描述、必需参数和有效值。助手通常会先调用此工具，查看有哪些数据可用。

billingserv_get

调用一个在允许列表中的 BillingServ API v2 GET 端点。

{
  "endpoint": "customer/get",
  "query": { "id": 123 }
}

路径中带有占位符的端点应改用 path 对象：

{
  "endpoint": "meter/{customer_id}/get/{order_id}",
  "path": { "customer_id": 123, "order_id": 456 }
}

billingserv_create

通过允许列表中的 POST 端点创建或更新记录。此工具还可以激活、验证和停用软件许可证。如果你希望在更改任何内容前先确认，可在 MCP 客户端中设置此工具需经批准后才能使用。

{
  "endpoint": "ticket/create",
  "body": {
    "subject": "Question about my last invoice",
    "user_id": 123,
    "message": "Customer called about a duplicate charge.",
    "support_department": "billing"
  }
}

可用端点

区域	端点
客户	customer/lists, customer/get, customer/get-credit
发票	invoice/lists, invoice/get-payment-method, invoice/get-transactions
订单	order/get-orders, order/get-orders-by-status, order/available-package-changes, order/preview-package-change, order/check-fraud
套餐	package/lists, package/get, package/show, package/get-by-customer, package/group/lists, package/group/get, package/option/lists, package/option/get
报告	report/annual-sales, report/revenue-trend, report/sales-by-staff, report/sales-by-customer, report/package-leaderboard, report/customer-receipt, report/customer-credit, report/customer-invoice, report/customer-debt, report/login-history
支持工单	ticket/lists, ticket/get
营销	marketing/lists, marketing/get-discount
用量计量	meter/{customer_id}/get/{order_id}
设置	setting/invoice, setting/lists-staff, setting/get-staff, setting/lists-tax-zone, setting/get-tax-zone, setting/lists-tax-class, setting/get-tax-class
VPN	vpn/branding/get, vpn/servers/list
地理信息	country/lists, country/get, county/lists-by-country
模块	module/get-module-configuration

以及这些可通过 billingserv_create 使用的写入端点：

区域	端点
支持工单	ticket/create, ticket/reply, ticket/update
订单	order/add-order
客户	customer/create, customer/add-note
发票	invoice/create-invoice, invoice/create-quote, invoice/send-invoice, invoice/send-invoice-reminder
套餐	package/create, package/update, package/group/create, package/group/update, package/option/create, package/option/update
营销	marketing/create-discount
许可	license/activate, license/validate, license/deactivate

套餐创建和更新支持 API 的 digital_delivery 对象，用于下载策略和软件许可控制。例如：

{
  "endpoint": "package/update",
  "body": {
    "id": 12,
    "group_id": 3,
    "name": "Desktop App",
    "digital_delivery": {
      "delivery_enabled": true,
      "download_policy": "cap_limited",
      "max_downloads": 5,
      "licensing_enabled": true,
      "activation_limit": 2,
      "offline_cache_minutes": 60
    }
  }
}

安全

• 端点允许列表已编译到服务中，并会在每次请求时进行检查。只能调用允许列表中的端点。
• 密码重置等敏感路由会被有意排除。
• API 密钥从环境中读取，且只会发送到你配置的基础 URL。它绝不会被记录或包含在工具输出中。
• 根据 API 要求，许可端点使用提交的许可证密钥作为凭据，因此 BillingServ bearer token 不会发送到这些路由。

开发

git clone https://github.com/billingserv/billingserv-mcp-server.git
cd billingserv-mcp-server
npm install
npm run build

BILLINGSERV_API_BASE_URL="https://billing.example.com/api/v2" \
BILLINGSERV_API_KEY="your_api_key" \
npm start

或者，将变量放入本地 .env 文件（已加入 gitignore），然后运行 npm run start:dev。

许可证

MIT