# Buy Me a Coffee (read-only)

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/mayeu20/buymeacoffee-mcp  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/buy-me-a-coffee-read-only

## Description
Read your own Buy Me a Coffee supporters, Extras purchases, memberships and totals.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "buy-me-a-coffee-read-only": {
    "command": "npx",
    "args": ["-y","buy-me-a-coffee-read-only"]
  }
}
```

## Documentation & 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, 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](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](https://github.com/mayeu20/buymeacoffee-mcp/blob/HEAD/LICENSE).