untappd-mcp

untappd-mcp

Untappd 向けの MCP サーバーです。自分のアカウントで Untappd のモバイル（v4）API に接続し、ビール、ブルワリー、店舗を検索したり、プロフィール、チェックイン、ウィッシュリスト、個別のビール、バッジ、友達、友達のアクティビティフィードを閲覧したり、チェックイン、乾杯、コメントを投稿したりできます。

AI（Claude Code）によって開発・保守されています。ご自身の判断でご利用ください。 これは Untappd の非公開モバイル API を使用する非公式クライアントであり、Untappd とは提携しておらず、承認も受けていません。

仕組み

Untappd の iPad／iPhone アプリは、ユーザー名とパスワードによる xauth ログイン（POST https://api.untappd.com/v4/xauth）でアクセストークンを取得してから、v4 API を呼び出します。このサーバーも同じ手順を再現しますが、トークンの送信方法は異なります。

• 読み取り時は、トークンを URL ではなく Authorization: Bearer ヘッダーで送信します（アプリは access_token クエリパラメーターを使用しますが、API はどちらも受け付けます）。
• 書き込み時も、トークンを Authorization: Bearer ヘッダーで送信します（アプリのクライアント認証情報はクエリに含めます）。これはアプリの実際のリクエストに合わせたものです。

トークンは必要に応じて取得され、メモリ内にキャッシュされます。期限切れになった場合は自動的に更新されます。

設定

変数	必須	説明
UNTAPPD_ACCESS_TOKEN	いいえ	すでにお持ちのアクセストークンです。これを指定すると、パスワードは不要になり、xauth ログインは完全にスキップされます。
UNTAPPD_USERNAME	トークンがない場合	Untappd のユーザー名またはログイン用メールアドレスです。
UNTAPPD_PASSWORD	トークンがない場合	Untappd のパスワードです（トークンを発行する xauth ログインでのみ使用されます）。
UNTAPPD_CLIENT_ID	ログインと書き込み時	Untappd モバイルアプリのクライアント ID です（下記を参照）。事前に設定したアクセストークンがあれば、これがなくても読み取りできます。
UNTAPPD_CLIENT_SECRET	ログインと書き込み時	Untappd モバイルアプリのクライアントシークレットです。
UNTAPPD_DEVICE_ID	いいえ	トークンに紐付ける固定のデバイス UUID です（デフォルト値が用意されています）。
UNTAPPD_UTV	いいえ	API バージョンパラメーターです（デフォルトは 4.0.0）。
UNTAPPD_USER_AGENT	いいえ	User-Agent を上書きします（デフォルトではアプリを模倣します）。
UNTAPPD_TIMEZONE	いいえ	timezone が呼び出し時に指定されていない場合に、チェックインのタイムスタンプに使用する IANA タイムゾーン（例：America/New_York）です。サーバーが飲む人のタイムゾーン以外の場所（例：通常 UTC となるホスト型コネクター）で動作する場合に設定してください。デフォルトではサーバープロセスのタイムゾーンが使用されます。
UNTAPPD_PHOTO_DIR	いいえ	untappd_checkin の photo_path を置くディレクトリです（複数指定する場合は : 区切りで指定します）。デフォルトは ~/Downloads/untappd-mcp です。写真を添付するには、このディレクトリに写真を置いてください。ほかのファイルは拒否されるため、プロンプトインジェクションされたシャウトやコメントによって、ディスク上の任意の画像が公開されることはありません。
UNTAPPD_CACHE_DB	いいえ	ローカルのチェックインキャッシュ SQLite ファイルのパスです（デフォルトは ~/.untappd-mcp/checkins.db）。相対パスまたは先頭に ~ が付いたパスは、作業ディレクトリではなくホームディレクトリを基準に解決されます。そのため、どのホスト（Claude Desktop、Claude Code、…）からも同じファイルを参照できます。解決されたパスは起動時に stderr に記録されます。データベースファイルは常に所有者のみがアクセスできるように設定され（0600）、サーバーが作成するディレクトリとデフォルトの ~/.untappd-mcp も同様です。指定先のディレクトリがすでに存在する場合、そのアクセス権は変更されません。ローカル／stdio のみで使用できます。
UNTAPPD_CACHE_DIR	いいえ	キャッシュ用のディレクトリです。~/.untappd-mcp の代わりに使用します（その中に checkins.db が作成されます）。両方が設定されている場合は、UNTAPPD_CACHE_DB が優先されます。

ローカルで使用するには、.env.example を .env にコピーして値を入力してください。

確認

書き込みを行うたびに、事前に確認が求められます。確認プロンプトを表示できるクライアント（Claude Code）では、プロンプトが表示されます（MCP_CONFIRM_ELICITATION=off の場合を除く）。それ以外の環境では、2 回の呼び出しが必要です。最初の呼び出しは何も実行せず、正確なリクエストのプレビューと confirmToken を返します。同じ引数とそのトークンを使って再度呼び出した場合にのみ、処理が実行されます。トークンは 1 回限り有効で、そのツールと引数の組み合わせに限られます。何かを変更すると、呼び出しは新しいプレビューとともに拒否されます。

変数	デフォルト
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で書き込みを行う場合の動作です。ask-user：2 段階で実行します。最初の呼び出しは何も実行せず、プレビューとトークンを返します。モデルはチャットであなたの承認を得てから、そのトークンを使って再度呼び出す必要があります。auto：同じく 2 段階で実行しますが、モデルはプレビューを自分で確認した後、トークンを使用できます。refuse：そのようなクライアントでは書き込みが拒否されます。プロンプトを表示できるクライアント（Claude Code）には、MCP_CONFIRM_ELICITATION=off でない限り、常に実際のプロンプトが表示されます。認識されない値は refuse として扱われます。
MCP_CONFIRM_ELICITATION	on	off にすると確認プロンプトは表示されず、すべてのクライアントで MCP_CONFIRM_MODE の動作が適用されます。プロンプトを表示できるとされているのに、実際には表示されないクライアント（書き込みが停止したままになる opencode 2.0.x）で設定してください。その他の値はすべて on として扱われ、stderr に警告が出力されます。
MCP_CONFIRM_TTL_SECONDS	600	トークンが有効な期間です。
MCP_CONFIRM_SECRET	プロセスごとにランダム	署名キーです。サーバー再起動後もトークンを有効にする必要がある場合にのみ設定してください。

クライアント ID／シークレットの取得

Untappd はこれらを公開していません。モバイルアプリ内にあります。HTTPS プロキシを使って、ご自身のアプリの通信から取得してください。

1. mitmproxy などのプロキシをインストールし、Untappd アプリを実行するデバイスでその CA 証明書を信頼するよう設定します。
2. デバイス（または、iPad アプリを実行している Apple シリコン搭載 Mac の場合は、Mac のシステム HTTP/HTTPS プロキシ）でプロキシを指定します。
3. Untappd を開いてサインインします。POST https://api.untappd.com/v4/xauth リクエストを探します。そのクエリー文字列に client_id と client_secret が含まれています。
4. それらを UNTAPPD_CLIENT_ID／UNTAPPD_CLIENT_SECRET に設定します。

これらの値は非公開にしてください。コミットしないでください。

ツール

読み取り：untappd_search_beer、untappd_beer_info、untappd_beer_activity、 untappd_search_brewery、untappd_brewery_info、untappd_brewery_beers、 untappd_search_venue、untappd_venue_info、untappd_venue_activity、 untappd_user_info、untappd_user_checkins、untappd_user_wishlist、 untappd_user_beers、untappd_user_badges、untappd_user_friends、untappd_pending_friends、 untappd_activity_feed、untappd_checkin_info、untappd_resolve、untappd_open_url、untappd_user_venues、untappd_venue_by_foursquare、untappd_trending、 untappd_notifications、untappd_local_checkins、untappd_healthcheck。

書き込み（いずれも事前に確認が求められます。詳細は確認をご覧ください）：untappd_toast、untappd_add_comment、untappd_delete_comment、untappd_checkin、 untappd_wishlist_add、untappd_wishlist_remove、untappd_delete_checkin、 untappd_add_friend、untappd_accept_friend、untappd_reject_friend、untappd_remove_friend。

チェックインキャッシュ：untappd_sync_checkins、untappd_sync_user_beers、 untappd_cache_has_had、untappd_cache_has_had_many、untappd_cache_not_had、 untappd_cache_query、untappd_top_not_had、untappd_cache_status、untappd_cache_forget。

メニューから選ぶ：untappd_menu_pick（タップリストの行を入力すると、未飲のビールを順位付きで返します）、 untappd_venue_pick（同様に、会場の Untappd メニューから選びます）。

メニューからビールを選ぶ

untappd_menu_pick を使うと、メニューの写真から「Mer のビールを探す」処理を1回の呼び出しで実行できます。 メニューに書かれた項目をそのまま渡します。

{
  "username": "mer",
  "items": [
    "HAP & HARRY'S TENNESSEE LAGER $6",
    "I BELIEVE IN NASHVILLE BLONDE",
    "JACKALOPE FENNARIO IPA",
    "BEARDED IRIS HOMESTYLE",
    "BLACK ABBEY SEASONAL",
    "ROTATING CIDER"
  ],
  "venue_city": "Nashville",
  "top_n": 2
}

1回の呼び出しで、次の処理を行います。

1. キャッシュを最新の状態にします。 ユーザーのビール一覧がすでに完全な場合は、キャッシュ済みで変更のない最初のビールが見つかった時点で終了する差分更新を行います（通常は1ページです）。一覧が空または不完全な場合は、完了するか api_budget（既定値は60回で、すべてのステップで共有）が尽きるまで、同じ呼び出し内でバックフィルします。先に同期ツールを呼び出す必要はありません。
2. 各項目をビールに対応付けます。 価格、サイズ、ABV、句読点を取り除いて Untappd を検索します（Untappd の検索はすべての語句に一致するため、スタイル名を除いたクエリでも検索します）。候補は、ブルワリーの一致、ビール名の一致（「Homestyle」が「Double Homestyle」と誤認されないようにします）、チェックイン数（チェックインが3件の重複項目より正規の項目を優先します）、および venue_city に基づいてスコアリングします。検索は最大4件まで同時に実行され、429 が返された場合はバックオフして再試行します。対応付け結果はディスクにキャッシュされるため、同じ店に次回来店した際の検索は不要です。
3. 一般的な項目を処理します。 <Brewery> SEASONAL／ROTATING は、そのブルワリーの季節限定と思われるビールの possible リストになり、needs_confirmation が設定されます。ブルワリー名がない項目（ROTATING CIDER）は、unresolved: "ask bartender" として返されます。
4. 各ビールをキャッシュと照合します（has_had_many と同様に、両方のソースを確認します）。
5. まだ飲んだことのないビールをグローバル評価でランク付けし、style_filter を適用して、上位 top_n 件を picks として返します。

Mer が Fennario を飲んだことがある場合の、上記の呼び出し結果（抜粋：not_had には評価3.33の Tennessee Lager も含まれ、possible には6件の候補が含まれます。また、freshness ブロックが追加されます）。

{
  "picks": [
    { "item": "BEARDED IRIS HOMESTYLE", "bid": 1502190, "name": "Homestyle", "brewery": "Bearded Iris Brewing",
      "style": "IPA - New England / Hazy", "abv": 6, "global_rating": 3.98,
      "reason": "not had · 3.98 global rating · #1 of 3 not-had beers on this list" },
    { "item": "I BELIEVE IN NASHVILLE BLONDE", "bid": 3780741, "name": "I Believe In Nashville",
      "brewery": "I Believe Brewing Company", "style": "Blonde / Golden Ale - American", "abv": 4.5,
      "global_rating": 3.54, "reason": "not had · 3.54 global rating · #2 of 3 not-had beers on this list" }
  ],
  "had": [
    { "item": "JACKALOPE FENNARIO IPA", "bid": 1893601, "name": "Fennario", "brewery": "Jackalope Brewing Company",
      "count": 3, "last_date": "2025-08-01T20:00:00.000Z", "user_rating": 3.75 }
  ],
  "possible": [
    { "item": "BLACK ABBEY SEASONAL", "brewery": "The Black Abbey Brewing Company",
      "reason": "seasonal-looking beers from this brewery",
      "candidates": [
        { "bid": 1223176, "name": "Chronicles Festbier", "style": "Festbier", "abv": 4.9, "global_rating": 3.672, "had": false }
      ],
      "needs_confirmation": true }
  ],
  "unresolved": [{ "item": "ROTATING CIDER", "reason": "ask bartender" }],
  "sync": { "mode": "backfill", "api_calls": 1 },
  "api_calls": 11,
  "api_budget": 60,
  "another_run_needed": false
}

sync は更新内容を示し、カバレッジは freshness に含まれます。バックフィルの完了前に予算が尽きると、freshness.coverage_complete は false、another_run_needed は true になり、freshness の注記で「飲んだことがない」という結果が誤検出の可能性があることを警告します。再度呼び出すと、中断した位置から続行します。

クォータ。 Untappd の応答に X-Ratelimit-Remaining が含まれている場合、サーバーはその値を1時間保持し、予算を消費するすべてのツール（menu_pick、venue_pick、top_not_had、両方の同期ツール）の予算を残りの値に制限します。その場合、結果には quota_remaining が含まれ、上限が適用されたときは budget_clamped_to_quota: true も含まれます。Untappd の公開 API ドキュメントにはこのヘッダーが記載されています。このサーバーが使用する非公開 API からヘッダーが送信されない場合、予算は従来どおりに機能します。

untappd_venue_pick には items の代わりに、Untappd の店舗 URL（https://untappd.com/v/<slug>/<id>）または ID を渡します。店舗の検証済みメニュー全体をページ単位で取得し、そこから店舗の市区町村を取得して、同じ照合とランキングを行います。メニュー項目にはすでにビール ID が含まれているため、検索のステップはありません。

チェックインキャッシュ

Untappd API で取得できるのはページ単位のリスト（1ページにつき50件）のみで、「このユーザーがビールXを飲んだことがあるか」を調べる方法はありません。この質問に API だけで答えるには、厳しい毎時約100回のレート制限のなかで、全履歴（チェックインが11,000件以上あることもよくあります）をページ取得する必要があります。これらのツールは SQLite ミラーを維持するため、API 呼び出しなしでオフラインでも即座に回答できます。ミラーはローカルの SQLite ファイル（node:sqlite、既定値は ~/.untappd-mcp/checkins.db、UNTAPPD_CACHE_DB／UNTAPPD_CACHE_DIR で変更可能）です。ストアは差し替え可能なため、ツールを変更せずに別のデプロイ環境で異なる方式にできます。

永続化。 ファイルは再起動後も保持され、中断されたバックフィル（レート制限、クラッシュ、ホストの終了など）は、次回の同期時に保存済みのオフセットから再開します。ファイルは WAL モードとビジータイムアウトを使用し、すべての書き込みをトランザクション内で実行するため、2台のホストから同時に開いて共有できます。スキーマにはバージョンが付けられ（PRAGMA user_version）、列とテーブルの追加による前方への移行のみを行うため、アップグレードでファイルが消去されることはありません。untappd_cache_status では、解決済みのパス、サイズ、スキーマのバージョン、ユーザーごとのカバレッジを確認できます。 2 つの同期ソースによってキャッシュが埋まります。

• untappd_sync_user_beers は user/beers をページングし、ユーザーの 重複のない全ビールリスト を取得します（数千行で、チェックインが数万件あるわけではありません）。 「飲んだことがある」範囲をすべて把握する最も手軽な方法であり、user/checkins とは異なり、公開アカウントでも友達のアカウントでも最後までページングできます。「飲んだことがあるか」に関する質問では、まずこちらを使ってください。
• untappd_sync_checkins は user/checkins をページングし、詳細なチェックイン情報（会場、日付、コメント）を取得します。最後までページングできるのは自分のアカウントだけです。Untappd は他のユーザーについては最新の約 50 件のみを返し、それ以上のページングはできないため、このツールは history_truncated と報告します（backfill_complete と誤って報告することはありません）。 誤って完了とマークされたキャッシュをリセットし、最新のチェックインから再度ページングするには force_backfill: true を指定してください（キャッシュ済みの行は保持されます）。最近の会場や日付の詳細を確認する場合に使い、「飲んだことがある」範囲を把握するには untappd_sync_user_beers を使ってください。

どちらも再開可能です。1 回の呼び出しにつき max_pages（デフォルトは 10）ページを取得し、各ページの取得後に進捗を保存します。完了するまで another_run_needed: true が設定されるため、false になるまで再度呼び出してください。

追加の API 呼び出しなしで、キャッシュをクエリできます。「飲んだことがあるか」を調べるツールは両方のソースを参照します（どちらか一方で見つかれば、飲んだことがあると判定します）。

• untappd_cache_has_had — 完全一致の bid または大文字小文字を区別しない beer_name の部分文字列で、ユーザーがそのビールを飲んだことがあるかを確認します。件数、最高評価、最終日、一致したソース、詳細なチェックインがあればその情報を返します。
• untappd_cache_has_had_many — bids のリスト全体を 1 回の呼び出しで照合します（例：会場のメニュー）。ビールごとに飲んだことがあるかどうかを返します。
• untappd_cache_not_had — bids のリストを受け取り、ユーザーがまだ飲んだことのないビールだけを返します。「このメニューで初めて飲むビールはどれ？」を調べるフィルターです。
• untappd_top_not_had — bids のリストから、Untappd の総合評価順に並べた未飲のビール上位 N 件を返します。任意で style フィルターを指定できます（「このタップリストから何を注文すべき？」を調べるツールです）。未飲の判定にはキャッシュのみを使います。ビールの評価はメタデータキャッシュ（beer_meta）から取得します。このキャッシュは untappd_beer_info／untappd_search_beer によって随時登録され、キャッシュミス時または登録から 30 日を超えた場合にのみ beer/info で補完されます。1 回の実行あたり api_budget（デフォルトは 25）件を上限とし、さらに補完が必要な場合は partial: true／another_run_needed: true を返します。
• untappd_cache_query — キャッシュ済みのチェックインを、ブルワリー、スタイル、min_rating、会場、日付範囲のいずれかまたは複数で絞り込み、並べ替えと件数制限を指定できます。

すべての読み取り結果には freshness ブロックが含まれ、各ソースの完了状況を個別に（checkins.backfill_complete／history_truncated、beers.complete、ソースごとの割合）示すほか、coverage_complete も報告します。また、範囲の取得が完了していない場合は caveat を付けるため、該当する同期が完了するまでは「見つからない」という結果が誤検出の可能性を含むことを示せます。

別のユーザーを同期する場合も、untappd_user_checkins と同じ認証済みエンドポイントを使用するため、Untappd のプライバシールールが適用されます。そのアカウントが公開されているか、あなたの友達である場合にのみ動作します。それ以外の場合、同期は相手を先に友達として追加するよう明示するエラーを返します。

保持期間。 キャッシュ内のデータは期限切れになりません。別のユーザーの日時付きチェックイン、コメント、会場を含め、同期済みの行は削除するまで保持されます。ファイルは所有者のみがアクセスできる状態で作成されます（ディレクトリは 0700、データベースは 0600。古いインストールも、開く際にアクセス権が厳格化されます）。untappd_cache_forget は確認後に、指定したユーザーのキャッシュ済みチェックイン、重複のないビールリスト、同期状態を削除します（プレビューにはユーザー名と行数が表示されます）。ローカルキャッシュのみを操作し、Untappd には一切アクセスしません。後から再同期してデータを再取得できます。ファイルを削除すると、すべてのデータが削除されます。

キャッシュに含まれるのは、そのキャッシュに関連付けられたアカウントが取得を許可されたチェックインのみです。untappd_healthcheck は実行中のバージョンと、ツールセットの正確な内容（件数、名前、安定したハッシュ）を報告するため、どのビルドが稼働しているかを確認できます。

開発

npm install
npm run build
npm test

ライセンス

MIT