Buy Me a Coffee (read-only)
Read your own Buy Me a Coffee supporters, Extras purchases, memberships and totals.
Open source Open in the app JSON README (API)
About
Read your own Buy Me a Coffee supporters, Extras purchases, memberships and totals.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- mayeu20
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Last push
- 2026-09-09T13:06:30Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-09-09 16:02:13
- Updated
- 2026-09-09 16:02:13
- Origin id
io.github.mayeu20/buymeacoffee-mcp
README
# 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
| Tool | What it returns | Arguments |
| --- | --- | --- |
| `list_supporters` | Recent one-off supports, newest first | `limit` (20), `since`, `include_emails` (false), `max_pages` (5) |
| `list_extra_purchases` | Recent Extras purchases | `limit` (20), `since`, `include_emails` (false), `max_pages` (5) |
| `list_subscriptions` | Membership records or an empty result with a message | `include_emails` (false), `max_pages` (5) |
| `summary` | Supports and Extras totals by currency, with a separate free support count | `days` (30), `max_pages` (20) |
`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. List results report `has_more`. Subscriptions return an error if the page cap leaves data unread. Missing normalized fields are `null`.
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](https://developers.buymeacoffee.com/). 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:
```json
{
"mcpServers": {
"buymeacoffee": {
"command": "npx",
"args": ["-y", "buymeacoffee-mcp"],
"env": { "BMAC_TOKEN": "..." }
}
}
}
```
Restart Claude Desktop after saving.
## Claude Code
```sh
claude mcp add buymeacoffee -e BMAC_TOKEN=... -- npx -y buymeacoffee-mcp
```
Replace `...` with your token.
## Cursor
Add this to your Cursor MCP configuration:
```json
{
"mcpServers": {
"buymeacoffee": {
"command": "npx",
"args": ["-y", "buymeacoffee-mcp"],
"env": { "BMAC_TOKEN": "..." }
}
}
}
```
## Codex CLI
```sh
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
```sh
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](LICENSE).