untappd

untappd-mcp-server

Untappd API を AI エージェント向けのツールとして公開する Model Context Protocol（MCP）サーバーです。Untappd v4 の読み取り API 全体をカバーする 27 個のツールに、組み込みのインタラクティブな OAuth 認証機能を備えています。店舗、醸造所、ビールの検索、チェックインフィードによるタップ中のビールの確認、ユーザーのバッジ、友達、ウィッシュリスト、飲酒履歴の閲覧、統計の集計を、あらゆる MCP 対応クライアントから利用できます。

前提条件

• Node.js 20+
• untappd.com/api から取得した Untappd API 認証情報（client_id と client_secret）
• 任意：認証が必要なツールを利用するための Untappd OAuth アクセストークン。チャット内で authenticate_untappd ツールを使うか、npx untappd-mcp-server auth を実行して取得できます（インタラクティブ認証を参照）

クイックスタート

npx を使う（インストール不要）

UNTAPPD_CLIENT_ID=xxx UNTAPPD_CLIENT_SECRET=yyy npx untappd-mcp-server

PowerShell

$env:UNTAPPD_CLIENT_ID = "your_client_id"
$env:UNTAPPD_CLIENT_SECRET = "your_client_secret"
npx untappd-mcp-server

Claude Desktop

Claude Desktop の設定（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "untappd": {
      "command": "npx",
      "args": ["untappd-mcp-server"],
      "env": {
        "UNTAPPD_CLIENT_ID": "your_client_id",
        "UNTAPPD_CLIENT_SECRET": "your_client_secret",
        "UNTAPPD_ACCESS_TOKEN": "optional_oauth_token",
        "UNTAPPD_USERNAME": "optional_default_username"
      }
    }
  }
}

ツール

🔑 token のマークが付いたツールには、アクセストークン（UNTAPPD_ACCESS_TOKEN 環境変数またはインタラクティブ認証）が必要です。

認証ツール

authenticate_untappd

OAuth を使って Untappd の認証をインタラクティブに行います。Untappd の承認ページをブラウザーで開き、一時的な localhost リスナーでリダイレクトを受信して、アクセストークンを保存します。🔑 ツールは再起動せずにすぐ使用できます。前提条件： Untappd アプリの Callback URL は http://localhost:8737/callback（または UNTAPPD_REDIRECT_URL の値）に正確に設定する必要があります。

パラメーター	型	必須	説明
timeout_seconds	integer	いいえ	ブラウザーでの承認を待つ時間（デフォルトは 180、最大は 600）

get_auth_status

認証状態を報告します。トークンの有無、取得元（環境変数またはトークンファイル）、ファイルパス、🔑 ツールが利用可能かどうかを確認できます。デフォルトでは無料で利用できます。validate: true を指定すると、API を 1 回呼び出してトークンを検証します。

パラメーター	型	必須	説明
validate	boolean	いいえ	API を 1 回呼び出してトークンを検証します（デフォルトは false）

検索と照会

venue_search

場所を考慮した検索を必要に応じて行い、名前で店舗（醸造所、バー、レストラン）を検索します。

パラメーター	型	必須	説明
q	string	はい	検索クエリ（店舗名）
lat	number	いいえ	場所を考慮した検索結果に使う緯度
lng	number	いいえ	場所を考慮した検索結果に使う経度

search_brewery

名前で醸造所を検索します。

パラメーター	型	必須	説明
q	string	はい	醸造所名の検索クエリ
offset	integer	いいえ	ページネーションのオフセット

search_beer

名前でビールを検索します。

パラメーター	型	必須	説明
q	string	はい	ビール名の検索クエリ
offset	integer	いいえ	ページネーションのオフセット
sort	string	いいえ	並べ替え順：checkin（デフォルト）、name、count

店舗

get_venue_info

店舗の詳細情報と最近のチェックインを取得します。

パラメーター	型	必須	説明
venue_id	integer	はい	Untappd の店舗 ID
compact	boolean	いいえ	true の場合、店舗情報のみを返します（チェックイン、メディア、人気のビールは含みません）

get_venue_checkins

会場の最近のチェックインフィードを取得します。現在提供されているビールを確認するための主要なツールです。最近のチェックインは、提供中のビールを示すリアルタイムの情報源になります。

パラメーター	型	必須	説明
venue_id	integer	はい	Untappd の会場 ID
limit	integer	いいえ	結果数（最大 25、デフォルト 25）
max_id	integer	いいえ	このチェックイン ID より古い結果を返します
min_id	integer	いいえ	この ID より新しいチェックインのみを返します

get_venue_foursquare_lookup

Foursquare の会場 ID を対応する Untappd の会場に解決します。Foursquare の位置情報と Untappd の会場ツールをつなぐ機能です。

パラメーター	型	必須	説明
foursquare_id	string	はい	v2 の MD5 ハッシュ形式の Foursquare 会場 ID（v3 の数値 ID は使用できません）

ビール

get_beer_info

特定のビールの詳細情報を取得します。

パラメーター	型	必須	説明
bid	integer	はい	Untappd のビール ID
compact	boolean	いいえ	true の場合、ビール情報のみを返します

get_beer_checkins

特定のビールの最近の公開チェックインフィードを取得します。現在、人々がそのビールについてどのように話しているか、どこで飲んでいるかを確認できます。

パラメーター	型	必須	説明
bid	integer	はい	Untappd のビール ID
limit	integer	いいえ	1 ページあたりの結果数（最大 50、デフォルト 25）
max_id	integer	いいえ	このチェックイン ID より古い結果を返します
min_id	integer	いいえ	この ID より新しいチェックインのみを返します

get_trending_beers

世界的にトレンドになっているビールを取得します（最近のチェックイン数の伸びに基づく大手・小規模ブルワリーのリスト）。パラメーターはありません。

ブルワリー

get_brewery_info

ブルワリーの詳細情報、ビール一覧、最近のチェックインを取得します。

パラメーター	型	必須	説明
brewery_id	integer	はい	Untappd のブルワリー ID
compact	boolean	いいえ	true の場合、ブルワリー情報のみを返します

get_brewery_checkins

ブルワリーの最近の公開チェックインフィードを取得します。世界中でチェックインされている、そのブルワリーのすべてのビールが対象です。

パラメーター	型	必須	説明
brewery_id	integer	はい	Untappd のブルワリー ID
limit	integer	いいえ	1 ページあたりの結果数（最大 50、デフォルト 25）
max_id	integer	いいえ	このチェックイン ID より古い結果を返します
min_id	integer	いいえ	この ID より新しいチェックインのみを返します

ユーザー

get_user_info

Untappd ユーザーのプロフィールと統計情報を取得します。

パラメーター	型	必須	説明
username	string	はい	Untappd のユーザー名
compact	boolean	いいえ	true の場合、ユーザー情報のみを返します（チェックイン、メディア、最近の醸造ビールは含まれません）

get_user_activity

ユーザーの最近のチェックインアクティビティフィードを取得します。

パラメーター	型	必須	説明
username	string	はい	Untappd のユーザー名
limit	integer	いいえ	結果数（最大 25、デフォルト 25）
max_id	integer	いいえ	このチェックイン ID より古い結果を返します
min_id	integer	いいえ	この ID より新しいチェックインのみを返します

get_user_distinct_beers

ユーザーがチェックインしたビールを重複なしで取得し、柔軟な並べ替えに対応します。sort=checkin と limit=1 の組み合わせは、「最も多くチェックインしたビール」を 1 回の呼び出しで取得するパターンです。

パラメーター	型	必須	説明
username	string	はい	Untappd のユーザー名
offset	integer	いいえ	ページネーションのオフセット
limit	integer	いいえ	1 ページあたりの結果数（最大 50、デフォルト 25）
sort	string	いいえ	date（デフォルト）、checkin、highest_rated、lowest_rated、highest_rated_you、lowest_rated_you

get_user_wishlist

ユーザーのウィッシュリストに登録されているビールを取得します。

パラメーター	型	必須	説明
username	string	はい	Untappd のユーザー名
offset	integer	いいえ	ページネーションのオフセット
limit	integer	いいえ	1 ページあたりの結果数（最大 50、デフォルト 25）
sort	string	いいえ	date（デフォルト）、checkin、highest_rated、lowest_rated

get_user_badges

ユーザーが獲得したバッジを取得します（1 ページ 50 件、新しい順）。

パラメーター	型	必須	説明
username	string	はい	Untappd のユーザー名
offset	integer	いいえ	ページネーションのオフセット（1 ページ 50 件）

get_user_friends

ユーザーの友達リストを取得します（公開アカウントのみ）。

パラメーター	型	必須	説明
username	string	はい	Untappd のユーザー名
offset	integer	いいえ	ページネーションのオフセット
limit	integer	いいえ	1 ページあたりの結果数（最大 50、デフォルト 25）

アクティビティフィード

get_global_feed

公開されているグローバルなチェックインフィード（The Pub）を取得します。返されるデータ量に対するレート制限のコストが高いため、新しいチェックインのみを取得する min_id によるポーリングを推奨します。注意： 標準の API キーでは通常 /thepub の利用が許可されていません。キーに拡張アクセス権がない限り、Untappd は "You are not authorized to call this method from this key" を返します（get_local_feed には制限がありません）。

パラメーター	型	必須	説明
limit	integer	いいえ	1 ページあたりの結果数（最大 50、デフォルト 25）
max_id	integer	いいえ	このチェックイン ID より古い結果を返します
min_id	integer	いいえ	この ID より新しいチェックインのみを返します

get_local_feed

地理的な地点の近くにある公開チェックインフィードを取得します。

パラメーター	型	必須	説明
lat	number	はい	緯度
lng	number	はい	経度
radius	integer	いいえ	半径（マイル。デフォルト 25、最大 50）
limit	integer	いいえ	1 ページあたりの結果数（最大 50、デフォルト 25）
max_id	integer	いいえ	このチェックイン ID より古い結果を返します
min_id	integer	いいえ	この ID より新しいチェックインのみを返します

get_friend_feed 🔑 token

認証済みユーザーの友達のチェックインフィードを取得します。

パラメーター	型	必須	説明
limit	integer	いいえ	1 ページあたりの結果数（最大 50、デフォルト 25）
max_id	integer	いいえ	このチェックイン ID より古い結果を返します
min_id	integer	いいえ	この ID より新しいチェックインのみを返します

チェックイン

get_checkin_info

バッジの獲得状況、乾杯、コメントなど、特定のチェックインの詳細情報を取得します。

パラメーター	型	必須	説明
checkin_id	integer	はい	Untappd のチェックイン ID

複合／集計

これらのツールは複数の API 呼び出しを行います（スキャンするページごとに 1 回。ビール／バッジは 50 件、チェックインは 25 件）。開始前に残りのレート制限を確認し、上限に近づいた場合は早期に停止して、レスポンスの truncated: true を設定します。

get_user_stats_at_venue

ユーザーの最近のチェックインフィードをスキャンし、特定の会場でのチェックイン統計（訪問回数、最終訪問日、平均評価、人気のビール）を取得します。Untappd の API には会場履歴のエンドポイントがないため、統計の対象はスキャンした期間（max_pages × 25 件のチェックイン）に限られ、全期間ではありません。

パラメーター	型	必須	説明
venue_id	integer	はい	Untappd の会場 ID
username	string	いいえ	Untappd のユーザー名（デフォルトは UNTAPPD_USERNAME）
max_pages	integer	いいえ	1 ページ 25 件のチェックインとしてスキャンするフィードの最大ページ数（デフォルト 5 = 125 件のチェックイン）

search_venue_then_get_user_stats

会場名で検索し、最上位の一致候補におけるユーザーのチェックイン統計を取得します。

パラメーター	型	必須	説明
q	string	はい	会場の検索クエリ
username	string	いいえ	Untappd のユーザー名（デフォルトは UNTAPPD_USERNAME）
lat	number	いいえ	位置情報に基づく検索に使用する緯度
lng	number	いいえ	位置情報に基づく検索に使用する経度
max_pages	integer	いいえ	25 件のチェックイン／ページでスキャンするフィードの最大ページ数（デフォルトは 5＝125 件のチェックイン）

get_user_beer_stats

ユーザーの重複しないビール履歴を集計し、スタイル、醸造所、評価の内訳を取得します。上位のスタイル、上位の醸造所、個人評価と全体評価の平均、最高評価、およびチェックイン数最多のビールが含まれます。

パラメーター	型	必須	説明
username	string	はい	Untappd のユーザー名
max_pages	integer	いいえ	50 件のビール／ページでスキャンする最大ページ数（デフォルトは 10＝500 件のビール）

get_user_badge_summary

ユーザーのすべてのバッジを（最後までページネーションして）取得し、構造化されたサマリーを返します。

パラメーター	型	必須	説明
username	string	はい	Untappd のユーザー名
max_pages	integer	いいえ	50 個のバッジ／ページでスキャンする最大ページ数（デフォルトは 10＝500 個のバッジ）

レート制限

Untappd API では、API キーごと（認証済みの場合はアクセストークンごと）に1 時間あたり 100 回の呼び出しが許可されています。各ツールの応答には、現在のレート制限状況が含まれます。

{
  "rateLimit": {
    "limit": 100,
    "remaining": 97
  }
}

複合ツールはページネーションを開始する前に assertRateLimitSufficient を呼び出し、予算を使い切るのではなく、早期に truncated: true を付けて停止します。制限を超えると、Untappd API は 429 エラーを返し、次のように表示されます：Rate limit exceeded. Limit: 100, Remaining: 0. Resets hourly.

認証

モード	環境変数	利用可能になる機能
パブリック	UNTAPPD_CLIENT_ID + UNTAPPD_CLIENT_SECRET	すべてのパブリックツール
認証済み	+ UNTAPPD_ACCESS_TOKEN（+ 任意の UNTAPPD_USERNAME）	get_friend_feed、ユーザー単位のレート制限、より詳細な /user データ

アクセストークンが設定されている場合（環境変数または保存済みトークンファイル）、サーバーはすべての呼び出しでアクセストークンを優先します。レート制限はユーザー単位になり、/user エンドポイントからより詳細なデータが返されます。UNTAPPD_USERNAME を設定すると、認証済みユーザーツールで使用するデフォルトのユーザー名を指定できます。

クライアント ID とシークレットのペアもアクセストークンも設定されていない場合、サーバーは起動時に終了します。

対話型認証

アクセストークンを手動で取得する必要はありません。サーバーが Untappd の OAuth フローを実行できます。

一度だけ必要な設定： Untappd アプリの設定 untappd.com/api で、Callback URL を次の値に正確に設定してください。

http://localhost:8737/callback

（上書きする場合は UNTAPPD_REDIRECT_URL の値を設定します。localhost の http URL である必要があり、2 つの値が完全に一致しないと Untappd がフローを拒否します）。

チャットでの操作： エージェントに authenticate_untappd ツールを実行するよう依頼してください。ブラウザーで Untappd の承認ページが開き、承認するとトークンが保存され、🔑 ツールがすぐに使えるようになります。再起動は不要です。

ターミナルでの操作：

npx untappd-mcp-server auth            # run the interactive flow
npx untappd-mcp-server auth --status   # show current auth status
npx untappd-mcp-server auth --clear    # delete the saved token

（リポジトリでは npm run auth を実行します）。

保存場所と優先順位： トークンは ~/.untappd-mcp-server/token.json に保存されます（UNTAPPD_TOKEN_PATH で変更可能）。UNTAPPD_ACCESS_TOKEN が設定されている場合は、常にファイルの値より優先されます。Untappd のトークンに有効期限はありません。

セキュリティに関する注意： トークンは macOS/Linux では権限 0600 でプレーンテキスト保存されます。Windows ではユーザープロファイルの ACL によって保護されます。auth --clear を実行すれば、いつでも削除できます。ツールの出力にトークンが含まれる場合は、常にマスクされた形式になります。

開発

npm install
npm run build
npm test          # unit tests (mocked API — no rate limit cost)
npm run smoke     # live smoke test against the real API (~25 calls, ~26 with a token)

スモークテストでは UNTAPPD_* 環境変数が使用され、アクセストークンが設定されていない場合は認証済みツールがスキップされます。また、残りのレート制限が 5 未満になると中止されます。npm run smoke -- --only=tool_name を使用すると、単一のツールに絞り込めます。

MCP Inspector でのテスト

npx @modelcontextprotocol/inspector node dist/index.js

既知の制限事項

• タップリストのデータはありません — 実際のタップリストを利用するには、Untappd for Business のサブスクリプションが必要です。会場のチェックインフィードをリアルタイムの代替として使用します。
• 会場イベントはありません — Untappd の公開 API にはイベントエンドポイントがなく、この不足を補える可能性があった Eventbrite の検索 API も廃止されたため、v3 での対応に延期されています。
• 会場履歴エンドポイントはありません — v4 API にはユーザーごとの会場履歴がありません。get_user_stats_at_venue は代わりに最近のチェックインフィードをスキャンするため、統計の対象は全期間ではなく、一定の期間（max_pages × 25 件のチェックイン）です。
• レート制限：100 件／時間 — 重複する呼び出しを最小限に抑えてください。すべてのレスポンスに rateLimit.remaining が表示されます。
• フィードの上限 — ツールで指定できる limit は最大 50 ですが、一部のフィードは API によってサーバー側で 25 件に制限されます。
• グローバルフィードには昇格済みキーが必要です — /thepub（get_global_feed）は標準 API キーでは認証されません。ローカルフィードはどのキーでも使用できます。
• Foursquare の検索には v2 ID が必要です — MD5 ハッシュ形式です。Foursquare v3 の数値 ID は使用できません。
• 会場 ID が必要です — まず venue_search を使用して、会場名を ID に変換してください。
• 公開チェックインのみ — 非公開ユーザーアカウントは表示されません。
• 読み取り専用 — 書き込み操作（チェックイン、乾杯、コメント、ウィッシュリストの管理）は v3 での対応に延期されています。
• MCP クライアントのタイムアウト — 一部の MCP クライアントでは、ツール呼び出しの時間制限が authenticate_untappd のデフォルトである 180s より短く設定されています。クライアント側で先にタイムアウトする場合は、より短い timeout_seconds を指定するか、代わりにターミナルで npx untappd-mcp-server auth を使用してください。

ライセンス

MIT