Billingserv

BillingServ MCP サーバー

BillingServ 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 キー

設定

以下の各クライアントのセットアップでは、同じ 3 つの環境変数を使用します。

変数	必須	説明
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

コマンドを 1 つ実行します。

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

設定 → 開発者 → 設定を編集 を開き、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
• 環境： 設定 の環境変数

ツール

このサーバーは、アシスタントに 3 つのツールを提供します。

billingserv_list_endpoints

サーバーが呼び出せるすべての BillingServ エンドポイントを、説明、必須パラメーター、有効な値とともに一覧表示します。アシスタントは通常、利用可能なデータを確認するため、最初にこのツールを呼び出します。

billingserv_get

許可リストに登録された BillingServ API v2 の GET エンドポイントを 1 つ呼び出します。

{
  "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 のベアラートークンはこれらのルートに送信されません。

開発

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