buymeacoffee-mcp

Read your own Buy Me a Coffee account from an AI assistant. This MCP server runs over stdio and uses the official read-only API.

See recent supporters, Extras purchases, memberships, and totals by currency. This project is independent and not affiliated with Buy Me a Coffee. Buy Me a Coffee is a trademark of its owner.

Tools

limit accepts 1 to 100. days accepts 1 to 365. since accepts an ISO date or a timestamp with a timezone. max_pages accepts 1 to 20 per endpoint. Requests are spaced at least one second apart, so a 20-page walk takes about 20 seconds. Missing normalized fields are null. Every argument also carries its own description in the tool schema, so your client can show you this detail inline.

The two list tools and the two counting tools behave differently when they run out of pages, and it is the difference worth knowing:

• list_supporters and list_extra_purchases return what they found and set has_more. A result is not the whole story until has_more is false.
• list_subscriptions and summary return an error instead, naming the cap. Neither will hand back a partial membership list or a total computed over part of the window, because a short total reads exactly like a real one.

since filters after the rows are fetched rather than at the API, so asking for more history than max_pages covers gives you a partial window, not an error.

Summary checks newest-first ordering within and across pages for each endpoint. It stops after a whole page falls before the window, provided no ordering break was seen. A final page with next_page_url: null always completes the walk. If ordering breaks, summary keeps walking and returns an error if the cap leaves pages unread. early_stop says whether older pages were skipped; pages_fetched counts all fetched pages across both endpoints. The API serves five rows per page.

Summary excludes refunded supports and revoked purchases. supports.count includes free supports. supports.free_count counts non-refunded, in-window supports with amount zero, including free downloads. Subtract it from supports.count for the paid support count. Currency totals are unchanged.

Getting a token

Open the Buy Me a Coffee developer dashboard. Select Login and sign in with your creator account. In the developer dashboard, select "generate my token", give it a name, and select "generate". Copy the token into your client's BMAC_TOKEN setting.

Claude Desktop

Use node 20 or newer. Add this entry to your Claude Desktop MCP configuration:

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

Restart Claude Desktop after saving.

Claude Code

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

Replace ... with your token.

Cursor

Add this to your Cursor MCP configuration:

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

Codex CLI

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

Replace ... with your token.

Privacy

Emails are redacted by default as j***@example.com, including emails in notes and nested records. Set include_emails: true only when you need full addresses. This is data from the account owner's account and should be handled accordingly.

The server reads the token only from BMAC_TOKEN. It stays in the local process and is sent only to developers.buymeacoffee.com for authentication. The server contacts no other host, writes no files, and logs nothing. Tool results go to your assistant. There is no telemetry.

HTTP 403 and client fingerprints

The API can reject a client fingerprint with HTTP 403 and error code 1010. This may be a client-fingerprint block rather than a bad token. The server sends a browser-like User-Agent on every request. If a block persists, try again later. HTTP 429 means the API has throttled requests.

Development

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

Tests use synthetic fixtures and a local HTTP server. The live test is skipped unless both BMAC_LIVE=1 and BMAC_TOKEN are set. It uses your real account and makes three read-only requests. Never put a token in a tracked file.

scripts/probe-shape.mjs prints the API response shape without values, for verifying against a real account.

The API documentation is marked unmaintained. Field mappings, date assumptions, and page-cap behavior are recorded in NOTES.md in the repository.

Licence

MIT. Copyright 2026 Mathieu Kessler. See LICENSE.