Untappd MCP

untappd-mcp

An MCP server for Untappd. It talks to Untappd's mobile (v4) API using your own account — search beers, breweries, and venues; read profiles, check-ins, wishlists, distinct beers, badges, friends, and your friend activity feed; and post check-ins, toasts, and comments.

Developed and maintained by AI (Claude Code). Use at your own discretion. This

is an unofficial client that uses Untappd's private mobile API; it is not

affiliated with or endorsed by Untappd.

How it works

Untappd's iPad/iPhone app authenticates with a username/password xauth login (POST https://api.untappd.com/v4/xauth) that returns an access token, then calls the v4 API. This server reproduces that, except where the token goes:

• Reads carry the token as an Authorization: Bearer header, never in the URL (the app uses an access_token query param; the API accepts both).
• Writes carry it as an Authorization: Bearer header (with the app's client credentials in the query), matching the app's real requests.

The token is fetched on demand, cached in memory, and refreshed automatically if it goes stale.

Configuration

Copy .env.example to .env and fill it in for local use.

Confirmations

Every write asks you to confirm it first. A client that can show a confirmation prompt (Claude Code) shows one (unless MCP_CONFIRM_ELICITATION=off). Elsewhere the write takes two calls: the first does nothing and returns a preview of the exact request plus a confirmToken, and only a repeat call with the same arguments and that token performs it. A token works once, for that tool and those arguments only; change anything and the call is refused with a fresh preview.

Obtaining the client id / secret

Untappd does not publish these; they live in the mobile app. Capture them from your own app's traffic with an HTTPS proxy:

1. Install a proxy such as mitmproxy and trust its CA certificate on the device running the Untappd app.
2. Point the device (or, on an Apple-silicon Mac running the iPad app, the Mac's system HTTP/HTTPS proxy) at the proxy.
3. Open Untappd and sign in. Find the POST https://api.untappd.com/v4/xauth request — its query string contains client_id and client_secret.
4. Put those into UNTAPPD_CLIENT_ID / UNTAPPD_CLIENT_SECRET.

Keep these values private; do not commit them.

Tools

Reads: 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_upload_slots, untappd_healthcheck.

Writes (each asks you to confirm first — see Confirmations): 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.

Check-in photos

untappd_checkin takes one photo (JPEG or PNG, max 15 MB) through exactly one of:

• `photo_path` — a file on the machine the server runs on, inside UNTAPPD_PHOTO_DIR. Local installs only: on the hosted connector the server can't see your files, so a path is refused with directions to the slot flow below.
• `photo_inline` — {filename, contentBase64, mimeType?}. Works anywhere; fine for a small photo, but every byte rides inside the tool call.
• `photo_blob_key` — the hosted connector's route. untappd_upload_slots (slots: [{filename}]) returns a signed upload URL and a ready curl per photo; PUT the photo with it, then pass the slot's blobKey. It refuses on a deployment with no blob store.

Every route is checked the same way (image type, size cap, bytes that really are a JPEG/PNG), and the confirmation preview names the photo and its SHA-256 — a blob that changes between the preview and the confirmed call is refused (DRAFT_CHANGED). An uploaded blob is deleted only after the check-in and its photo succeed (photo_blob: {deleted: true}); otherwise it is kept (kept: true) so you can retry.

Check-in cache: 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_sync_wishlist (mirrors a user's wishlist locally so picks can boost wishlisted beers), untappd_sync_brewery_likes (mirrors the breweries a user likes/follows on Untappd, as "untappd" favorites), untappd_sync_user_venues + untappd_cache_has_visited (a user's full venue history — "has this person been here?" — which pages fully for any public/friend account, unlike their check-ins).

Trip planning: untappd_trip_check takes a user (or usernames + mode) and up to 25 stops — each a venue_id, a name (+ city/state), a lat/lng, and/or a brewery_id — and returns per stop: whether they've been there (first/recent visit, total visits, the matched venues incl. Untappd's "(duplicate of …)" copies; a brewery stop is matched by the brewery's name), how many of the brewery's beers they've had, and the top N (default 4) not-had beers by Untappd global rating, with an optional style filter (out-of-production beers skipped unless asked). Visits and has-had are answered from the cache only; the one API call it may make is brewery/beer_list for a brewery whose list isn't cached or is past its 7-day TTL — at most api_budget (default 5; 0 = strictly cache-only, using a stale list flagged stale), under the rate-limit guard. Favorite venues and breweries are flagged, prefer_favorites (default true) boosts wishlisted and favorite-brewery beers (liked on Untappd, derived or manual), and a stop within near_favorite_radius_m (default 2 km) of a favorite venue gets near_favorites and a "Near a favorite: …" hint.

Group checks: untappd_cache_has_had_many and untappd_top_not_had accept usernames (up to 10) with mode: "none_had" (default — beers new to everyone) or "any_not_had" (beers at least one of them still needs); each beer says who has and hasn't had it.

What they drank at a venue (opt-in, costs calls): untappd_sync_venue_drinks fetches the beer from each cached venue's first and most-recent visit check-in (checkin/view, budgeted by max_calls, stops before the rate limit). It's a partial picture — two check-ins per venue at most — shown in untappd_cache_has_visited as drinks.

Favorites (cache only, never written to Untappd): untappd_favorites_list lists a user's favorite beers, breweries and venues, each once with its sources and a reason. Derived favorites come from the synced history — venues with ≥5 check-ins or visits spanning ≥3 distinct months; breweries with ≥5 beers had and an average rating ≥3.75, or ≥15 beers; beers rated ≥4.25 or had ≥3 times — and every threshold can be overridden per call. Manual favorites are added and removed with untappd_favorite_add / untappd_favorite_remove (local table, optional note). Results from untappd_cache_has_had, untappd_cache_has_had_many, untappd_cache_has_visited, untappd_brewery_beers, untappd_venue_menu and untappd_top_not_had carry a favorite field {is_favorite, sources, reason}, and untappd_top_not_had ranks wishlisted beers and beers from favorite breweries higher by default (prefer_favorites: false turns that off); untappd_trip_check carries the same flags and boost.

Untappd favorites (breweries only): untappd_sync_brewery_likes mirrors the breweries a user "likes" on Untappd (user/brewerylikes — the app calls them "followings"; works for another user's public/friend account, ~50 per call). Like the wishlist sync it's a full pass from the top, resumable (cursor saved every page, another_run_needed, percent), stops before the rate limit with stopped_for_rate_limit + resume info, and only drops unliked breweries once a