Buy Me a Coffee (read-only)

buymeacoffee-mcp

AI アシスタントから、自分の Buy Me a Coffee アカウントを読み取れます。この MCP サーバーは stdio 経由で動作し、公式の読み取り専用 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 になります。各引数にはツールスキーマ内に説明も付いているため、クライアントで詳細をインライン表示できます。

2つのリスト取得ツールと2つの集計ツールでは、ページをすべて取得しきった場合の動作が異なります。この違いを把握しておくことが大切です。

• 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 は1ページあたり5行を返します。

summary では、返金されたサポートと取り消された購入は除外されます。supports.count には無料サポートも含まれます。supports.free_count は、返金されておらず、指定期間内にあり、金額が0のサポートの件数です。無料ダウンロードも含まれます。有料サポートの件数を求めるには、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 の両方が設定されている場合にのみ実行されます。このテストでは実際のアカウントを使用し、読み取り専用のリクエストを 3 回行います。トークンを追跡対象のファイルに記載しないでください。

scripts/probe-shape.mjs は、実際のアカウントとの照合に使用できるよう、値を含めずに API レスポンスの構造を出力します。

API ドキュメントはメンテナンスされていない旨が記載されています。フィールドのマッピング、日付の前提、ページ数の上限の動作については、リポジトリ内の NOTES.md に記録されています。

ライセンス

MIT。Copyright 2026 Mathieu Kessler。LICENSE を参照してください。