three.ws Billing

@three-ws/billing-mcp

MCP を通じて、AI エージェント自身のアカウントの利用状況を確認できます。プランのクォータ、従量課金の使用状況、請求書、領収書、収益を確認できます。読み取り専用で、アカウント単位にスコープされています。

---

Model Context Protocol サーバーです。stdio を通じて、AI エージェントが人間のアカウント所有者を介さずに、自身のアカウントの利用状況を確認できます。プランのクォータ残量、今期の従量課金の集計、すべての請求の明細と請求ごとの領収書、エージェントが得た収益を確認できます。

読み取りのたびに、ライブの three.ws 請求 API にアクセスします。モックはありません。アカウント単位の読み取りでは、three.ws のセッションから特定された、お客様が所有するアカウントを対象とします。このサーバーは読み取り専用です。非公開の請求データを表示しますが、署名、課金、資金移動は行いません。

インストール

npm install @three-ws/billing-mcp

または、npx でインストールせずに実行します。

npx @three-ws/billing-mcp

クイックスタート

Claude Code では、次の1行を実行します。

claude mcp add billing -- npx -y @three-ws/billing-mcp

Claude Desktop / Cursor（claude_desktop_config.json または mcp.json）：

{
	"mcpServers": {
		"billing": {
			"command": "npx",
			"args": ["-y", "@three-ws/billing-mcp"],
			"env": {
				"THREE_WS_SESSION": "<your __Host-sid cookie>"
			}
		}
	}
}

公開の手数料率を除くすべての読み取りには、THREE_WS_SESSION が必要です。これは、three.ws にサインインしたブラウザーセッションの __Host-sid Cookie の値です。API はこれを使ってアカウントを特定し、お客様のデータのみを返します。

MCP Inspector で機能を確認します。

npx -y @modelcontextprotocol/inspector npx @three-ws/billing-mcp

ツール

ツール	種類	機能
get_billing_summary	読み取り・セッション	お客様のプランのティア、クォータ上限、それに対する現在の使用状況（アバター＋ストレージ、エージェント、MCP 呼び出し、LLM 呼び出し）、および余裕を確認します。
query_usage	読み取り・セッション	指定期間の従量課金を請求明細にまとめ、アクションごとの項目、合計、照合結果を確認します。
export_billing_history	読み取り・セッション	同じ明細を、保存可能な CSV ペイロードとして出力します（推奨ファイル名と解析済みプレビューも含みます）。
get_receipt	読み取り・セッション	event_id による請求ごとの明細付き領収書（決済トランザクションとエクスプローラーへのリンクを含む）、または purchase_id による署名済みスキル購入領収書を取得します。
get_fee_info	読み取り・公開	現在のプラットフォーム手数料率（fee_bps ＋ fee_percent）を取得します。セッションは不要です。

すべての読み取りはライブの状態を取得します。使用状況や請求書は呼び出しの間に変わるため、どのツールも冪等ではなく、ここでデータが変更されることもありません。

入力パラメーター

get_billing_summary：なし。

query_usage：period（YYYY-MM、任意）、from / to（ISO-8601、任意。period が設定されている場合は無視されます）。デフォルトは現在の UTC 暦月です。

export_billing_history：period、from、to（query_usage と同じ）、preview_rows（0～100、デフォルトは 5。preview にエコーする解析済み行の数。CSV 全体は常に返されます）。

get_receipt：event_id（数値、請求ごとの領収書）または purchase_id（UUID、署名付きスキル購入領収書）のいずれか一方のみ。

get_fee_info：なし。

例

// get_billing_summary: plan ceilings and live usage against them
> {}
{
  "ok": true,
  "plan": "free",
  "quotas": {
    "max_avatars": 10,
    "max_bytes_per_avatar": 26214400,
    "max_total_bytes": 262144000,
    "mcp_calls_per_day": 1000
  },
  "usage": {
    "avatar_count": 1,
    "total_bytes": 1234540,
    "agent_count": 1,
    "mcp_calls_24h": 0,
    "llm_calls_month": 0
  },
  "remaining": { "avatars": 9, "total_bytes": 260909460, "mcp_calls_today": 1000 }
}

// query_usage: the period statement (defaults to the current UTC month)
> {}
{
  "ok": true,
  "period_label": "2026-08",
  "period": { "from": "2026-08-01T00:00:00.000Z", "to": "2026-09-01T00:00:00.000Z" },
  "line_item_count": 0,
  "line_items": [],
  "totals": {
    "charge_count": 0,
    "gross_atomics": "0", "fee_atomics": "0", "net_atomics": "0",
    "gross_usd": "0.00", "fee_usd": "0.00", "net_usd": "0.00",
    "currency": "USDC"
  },
  "reconciliation": { "total": 0, "reconciled": 0, "unreconciled": 0, "all_reconciled": true }
}

// export_billing_history: the same statement as a ready-to-save CSV
> { "preview_rows": 5 }
{
  "ok": true,
  "filename": "three-ws-invoice-2026-08.csv",
  "content_type": "text/csv; charset=utf-8",
  "row_count": 1,
  "preview": [ { "action": "TOTAL", "count": "0", "gross_usd": "0.00", "fee_usd": "0.00" } ],
  "csv": "action,label,count,units,gross_usd,fee_usd,discount_bps\nTOTAL,,0,,0.00,0.00,\n"
}

// get_fee_info: the one read that needs no session
> {}
{ "ok": true, "fee_bps": 250, "fee_percent": "2.5" }

利用状況のないアカウントでは、上記の明細のように、合計がゼロで all_reconciled: true と表示されます。これは正常な空の状態であり、呼び出しの失敗ではありません。 THREE_WS_SESSION がない状態での読み取りはすべて（get_fee_info を除く）、空のデータを返すのではなく、明確なエラーになります：

{ "ok": false, "error": "no_session", "status": 401,
  "message": "/api/billing/summary is account-scoped and needs your three.ws session. …" }

支払い内容

• 「これはいくらかかりましたか？」 → query_usage / export_billing_history / get_receipt で、従量課金、期間ごとの明細、個別の請求に対する領収書を確認できます。

get_billing_summary はこれらの概要を示し、ご利用中のプラン、上限、残りの利用可能枠を確認できます。

金額と単位

• 請求額は USDC の最小単位（小数点以下 6 桁）で示され、併せて人が読みやすい *_usd 文字列も返されます。たとえば、gross_atomics: "150000" は gross_usd: "0.15" です。
• 利用状況の読み取り結果にある reconciliation では、すべての従量課金が実際のオンチェーン決済に対応しているかどうか（all_reconciled と件数）を確認できます。

必要条件

• Node.js >= 20。
• https://three.ws（または独自の THREE_WS_BASE）へのネットワークアクセス。

環境変数

変数	必須	デフォルト
THREE_WS_BASE	いいえ	https://three.ws
THREE_WS_TIMEOUT_MS	いいえ	20000
THREE_WS_SESSION	はい（get_fee_info を除くすべての読み取り）	-

THREE_WS_SESSION は、サインイン済みの three.ws ブラウザーセッションにある __Host-sid Cookie の値です。パスワードと同様に扱ってください。これにより、非公開の請求データへの読み取りアクセスが許可されます。

リンク

• ホームページ：https://three.ws
• 変更履歴：https://three.ws/changelog
• Issue：https://github.com/nirholas/three.ws/issues
• ライセンス：Apache-2.0。詳細は LICENSE をご覧ください。

---

_{three.ws SDK スイートの一部です。3D AI エージェント、オンチェーン ID、エージェント決済を提供します。
ウェブサイト · 変更履歴 · GitHub}