Buy Me a Coffee (read-only)

buymeacoffee-mcp

通过 AI 助手读取你自己的 Buy Me a Coffee 账户。此 MCP 服务通过标准输入输出运行，并使用官方只读 API。

查看近期支持者、Extras 购买记录、会员信息以及按货币统计的总额。本项目独立开发，与 Buy Me a Coffee 无关。Buy Me a Coffee 是其所有者的商标。

工具

工具	返回内容	参数
list_supporters	近期的一次性支持记录，按时间从新到旧排列	limit（20）、since、include_emails（false）、max_pages（5）
list_extra_purchases	近期的 Extras 购买记录	limit（20）、since、include_emails（false）、max_pages（5）
list_subscriptions	会员记录，或附带说明的空结果	include_emails（false）、max_pages（5）
summary	按货币统计的支持和 Extras 总额，以及单独统计的免费支持数量	days（30）、max_pages（20）

limit 接受 1 到 100。days 接受 1 到 365。since 接受 ISO 日期或带时区的时间戳。每个端点的 max_pages 接受 1 到 20。请求之间至少间隔 1 秒，因此遍历 20 页大约需要 20 秒。缺失的标准化字段为 null。每个参数在工具架构中也有自己的说明，因此客户端可以直接向你展示这些详细信息。

两个列表工具和两个计数工具在达到页数上限时的处理方式不同，这一点值得了解：

• list_supporters 和 list_extra_purchases 会返回已找到的内容，并设置 has_more。只有当 has_more 为 false 时，结果才是完整的。
• list_subscriptions 和 summary 则会返回错误，并指出页数上限。两者都不会返回不完整的会员列表，也不会返回基于部分时间范围计算的总额，因为较小的总额看起来与真实总额完全一样。

since 会在获取行记录后进行筛选，而不是在 API 端筛选，因此，如果你请求的历史记录超出 max_pages 所覆盖的范围，就会得到不完整的时间范围，而不是错误。

对于每个端点，Summary 都会检查各页内及跨页的记录是否按从新到旧排列。如果整页记录都早于时间范围，且没有发现排序异常，就会停止。若最后一页的 next_page_url: null，则无论如何都会完成遍历。如果排序异常，summary 会继续遍历；如果达到上限时仍有页面未读取，则会返回错误。early_stop 表示是否跳过了较早的页面；pages_fetched 统计两个端点获取的所有页面数。API 每页返回 5 行记录。

Summary 不包括已退款的支持和已撤销的购买。supports.count 包括免费支持。supports.free_count 统计时间范围内未退款且金额为零的支持记录，包括免费下载。用 supports.count 减去该值即可得到付费支持数量。各货币的总额不变。

获取令牌

打开 Buy Me a Coffee 开发者控制面板。选择 Login，并使用创作者账户登录。在开发者控制面板中，选择 "generate my token"，为令牌命名，然后选择 "generate"。将令牌复制到客户端的 BMAC_TOKEN 设置中。

Claude Desktop

使用 node 20 或更高版本。将以下条目添加到 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "buymeacoffee": {
      "command": "npx",
      "args": ["-y", "buymeacoffee-mcp"],
      "env": { "BMAC_TOKEN": "..." }
    }
  }
}

保存后重启 Claude Desktop。

Claude Code

claude mcp add buymeacoffee -e BMAC_TOKEN=... -- npx -y buymeacoffee-mcp

将 ... 替换为你的令牌。

Cursor

将以下内容添加到 Cursor MCP 配置中：

{
  "mcpServers": {
    "buymeacoffee": {
      "command": "npx",
      "args": ["-y", "buymeacoffee-mcp"],
      "env": { "BMAC_TOKEN": "..." }
    }
  }
}

Codex CLI

codex mcp add buymeacoffee --env BMAC_TOKEN=... -- npx -y buymeacoffee-mcp

将 ... 替换为你的令牌。

隐私

默认会将电子邮件地址隐藏为 j***@example.com，包括备注和嵌套记录中的电子邮件地址。只有在需要完整地址时才设置 include_emails: true。这些数据来自账户所有者的账户，应妥善处理。

服务仅从 BMAC_TOKEN 读取令牌。令牌会保留在本地进程中，仅发送至 developers.buymeacoffee.com 用于身份验证。服务不会连接其他主机，不会写入文件，也不会记录日志。工具结果会发送给你的助手。本服务不收集遥测数据。

HTTP 403 和客户端指纹

API 可能会拒绝某个客户端指纹，并返回 HTTP 403 和错误代码 1010。这可能是客户端指纹被拦截，而不是令牌无效。服务器会在每个请求中发送类似浏览器的 User-Agent。如果拦截持续存在，请稍后重试。HTTP 429 表示 API 已限制请求。

开发

pnpm install
pnpm build
pnpm test
pnpm dev
npm pack --dry-run

测试使用合成测试数据和本地 HTTP 服务器。只有在同时设置 BMAC_LIVE=1 和 BMAC_TOKEN 时，才会运行实时测试。测试会使用你的真实账户，并发出三个只读请求。切勿将令牌放入受版本控制的文件中。

scripts/probe-shape.mjs 会打印 API 响应结构（不包含值），以便对照真实账户进行验证。

API 文档已标记为不再维护。字段映射、日期假设和分页上限行为记录在仓库的 NOTES.md 中。

许可

MIT。版权所有 2026 Mathieu Kessler。请参阅 LICENSE。