three.ws Billing

@three-ws/billing-mcp

通过 MCP 查看 AI Agent 自身的账户收支情况、套餐配额、计量用量、发票、收据和收益。只读且限定账户范围。

---

一个 Model Context Protocol 服务，让 AI Agent 通过 stdio 自行查询自己的账户收支情况：套餐配额还剩多少、本周期累计的计量用量、每笔费用对应的明细发票和收据，以及其 Agent 赚取的收益，全程无需联系人工账户所有者。

每次读取都会调用实时的 three.ws 账单 API：不使用任何模拟数据。账户范围内的读取操作会针对你拥有的账户执行，该账户根据你的 three.ws 会话确定。此服务为只读：它会展示私有账单数据，但绝不会签名、收费或转移资金。

安装

npm install @three-ws/billing-mcp

也可以使用 npx 运行（无需安装）：

npx @three-ws/billing-mcp

快速开始

Claude Code，只需一行：

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	读取 · 会话	查看你的套餐等级、配额上限，以及当前用量（头像 + 存储、Agent、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。这是正常的空状态，并非调用失败。除 get_fee_info 外，所有读取操作在没有 THREE_WS_SESSION 时都会明确报错，而不会返回空数据：

{ "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
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，参见 LICENSE

---

_{属于 three.ws SDK 套件，涵盖 3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}