io.github.chrischall/untappd-mcp

Accepts an incoming friend request (see untappd_pending_friends for pending uids). Acts on YOUR account and affects a real relationship with another person. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Note: this endpoint path is taken from the Untappd app but is not otherwise independently verified.

Get your Untappd friend activity feed — the recent check-ins from people you follow, newest first. Page backwards with max_id (the pagination.max_id from a prior call). Read-only.

Post a comment on a check-in from YOUR account. Writes to your Untappd account and is visible to others. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Sends a friend request to another user, who will be notified. Acts on YOUR account and affects a real relationship with another person. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Note: this endpoint path is taken from the Untappd app but is not otherwise independently verified.

Get the recent public check-ins for a beer by its bid — who drank it, their rating, comment, and venue. Page backwards with max_id (the pagination.max_id from a prior call). Read-only.

Get full detail for a beer by its Untappd beer id (bid): description, style, ABV, IBU, brewery, rating, total check-in count, and — on view:"full" — recent activity. Get a bid from untappd_search_beer. Read-only.

Get the beers a brewery makes, by brewery id, with per-beer global rating, check-in count, ABV, style and in_production. Supports sorting and paging. Get an id from untappd_search_brewery. Lists are CACHED locally for 7 days (source:"cache"|"api", fetched_at, expires_at): a fresh cached list answers without an API call — the default popularity order from the cached top-of-list, other sorts once the whole list is cached (sorted locally). refresh:true re-fetches. The compact result has the same keys with or without the cache (source:"api" and null fetched_at/expires_at when no cache is available), with pagination {offset, limit, next_offset}. Untappd's per-beer has_had / your-count on this endpoint describe the AUTHENTICATED account, never the user you are asking about, so have_had / your_count are never cached or returned on either path — use untappd_cache_has_had_many for any user. With the cache, the result carries favorite {is_favorite, sources, reason} for the brewery and on each favorite beer (derived from username's history or added with untappd_favorite_add; default your account). view:"full" always calls Untappd and returns its raw page. Read-only.

Get full detail for a brewery by its Untappd brewery id: description, location, type, rating, total check-ins, and popular beers. Get an id from untappd_search_brewery. Read-only. Its claimed_status.follow_status is whether the SIGNED-IN account follows/likes the brewery — never another user's; for theirs, run untappd_sync_brewery_likes and read untappd_favorites_list (source "untappd").

Delete everything the LOCAL cache holds for one user — their cached check-ins (beer, rating, comment, venue, date), distinct-beers list, venue history, wishlist copy, local favorites, venue drinks and sync state — e.g. after syncing a friend you no longer want a history of. Only the local cache is touched; nothing on Untappd changes, and a later sync can re-fetch it (manual favorites cannot be re-fetched). Shared beer, venue and brewery facts are kept. The preview shows the username and exactly how many rows will be removed. Omit username for your own account. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Answer "has this user ever checked in this beer?" from the cache only — NO API call. Consults BOTH cached sources (check-ins and the distinct-beers list); a hit in either counts as had. Match by exact bid or a case-insensitive substring of the beer name. Returns whether they had it, the times-had count, best rating, last date, which sources matched, any detailed check-ins, and favorite {is_favorite, sources, reason} (rated ≥4.25 / had ≥3 times, or added with untappd_favorite_add). Reports per-source freshness so you can caveat incomplete data. Requires bid or beer_name. Run untappd_sync_user_beers first for full coverage.

Cross-check a list of beer ids against a user's cached history in ONE call — NO API call. Consults BOTH sources (check-ins + distinct beers). Returns had/not-had per bid (with count and last date when had), plus favorite {is_favorite, sources, reason} per bid and brewery_favorite when its brewery (from cached beer metadata) is a favorite. Ideal for checking a whole venue menu at once. Pass usernames (instead of username) to check a GROUP: each bid then lists had_by / not_had_by and qualifies per mode — "none_had" (default: new to everyone) or "any_not_had" (at least one of them still needs it) — with qualifying_bids and a per-user freshness block. Run untappd_sync_user_beers first (for every user); the freshness block flags if coverage is incomplete.

Answer "has this user been here?" for one or many places in ONE call, from the cached venue history only — NO API call. Each query matches by exact venue_ids, by name (case-insensitive substring or all significant words, optionally narrowed by city/state), and/or by lat/lng within radius_m (default 150 m); venue_ids are unioned with the name/geo match, and name + lat/lng together must both hold. Name/location matching matters because a brewery_id is NOT its taproom's venue_id, a brewery can have several venues, and Untappd keeps "… (duplicate of …)" venues — so expect, and check, several matches. Returns per query: visited, the matched venues (first_visit, recent_visit, total_count, is_duplicate, distance_m, and — once untappd_sync_venue_drinks has fetched them — drinks: the beer from the first/recent visit check-ins — and favorite {is_favorite, sources, reason}: derived from the visit history or added with untappd_favorite_add), and total_visits; plus a freshness block (last_synced_at, coverage_complete, caveat). Run untappd_sync_user_venues first.

Given a list of beer ids, return only the ones the user has NOT had — the "what here is new to me?" filter for a venue menu, a brewery lineup, or a festival list. Consults BOTH cached sources; reads the cache only, NO API call. Returns the not-had bids (plus the had bids and counts) and cache freshness. Run untappd_sync_user_beers first; if coverage is incomplete the freshness caveat flags that a "not had" may be a false negative.

Query a user's cached CHECK-INS by brewery, style, minimum rating, venue, and/or date range, with sorting and a limit — from the cache only, NO API call. Reflects the detailed check-ins table (venue/date), which for non-self accounts is only the recent window; for full coverage of which beers a user has had, use untappd_cache_has_had / not_had instead. Run untappd_sync_checkins first.

Diagnostics for the LOCAL check-in cache — NO API call. Returns the resolved cache file path, its size on disk (db + WAL), journal mode, schema version, the number of cached menu-line resolutions and beer-metadata rows, cached venues, and for every cached user: cached vs total distinct beers, cached check-ins, coverage_complete, the resume offset of an unfinished user/beers backfill, last_synced_at, and venue-history coverage (venues: cached vs total, complete, percent, next_offset; null if never synced), wishlist and Untappd brewery-likes mirror coverage (wishlist / brewery_likes: cached vs total, complete; null if never synced). Also reports rate_limit: API calls made in the last hour (this process plus any other sharing the cache file), the ~100/hour limit, the estimated calls left, the raw X-Ratelimit-* headers (the v4 API sends Remaining: 0 on every success, so it is ignored until it reports a live value) and any 429 wait. Use it to confirm the cache persisted across restarts, to see how far a backfill has got, or to check whether a sync can run now.

Post a NEW beer check-in to YOUR Untappd account — this publishes to your public feed. Provide the beer id (bid) from untappd_search_beer; optionally a rating (0–5 in 0.25 steps), a shout (comment), a venue via foursquare_id, and a local photo via photo_path (JPEG/PNG). The preview shows the exact fields and photo that will be posted. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Get full detail for a single check-in by its id: the beer, rating, comment, photos, venue, badges earned, toasts, and comments. Get a check-in id from a feed or user-checkins result. Read-only.

Permanently delete one of YOUR check-ins by its id. This is destructive and cannot be undone. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Delete one of YOUR comments by its comment id (the id from a check-in's comments list). Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

Add a MANUAL favorite — a beer, brewery or venue — with an optional note, to the local cache. Local to the cache — NEVER writes to Untappd (Untappd has no favorites API for this). Re-adding an existing favorite updates its note (omit note to keep it) and keeps its created_at. Manual favorites show in untappd_favorites_list (source "manual") and as the `favorite` field on has_had, has_had_many, has_visited, brewery_beers, venue_menu, top_not_had and trip_check results; a favorite brewery also boosts its beers in untappd_top_not_had. Omit username for your own account.

Remove a MANUAL favorite (beer, brewery or venue) from the local cache. Local to the cache — NEVER writes to Untappd (Untappd has no favorites API for this). Returns removed:false when there was none. A DERIVED favorite (from the user's history) cannot be removed — it is computed from the thresholds; change them in untappd_favorites_list instead. Omit username for your own account.

List a user's favorites from the cache only — NO API call. Each item appears ONCE with every source that names it (sources: "derived" = qualifies from their cached history, "manual" = added with untappd_favorite_add, "untappd" = a brewery the user likes/follows on Untappd, mirrored by untappd_sync_brewery_likes — breweries only: Untappd has no followed/favorite venue list) and a reason ("liked on Untappd (since 2021-03)", "12 check-ins since 2015", "avg 4.1 across 9 beers", "manual: <note>"). Derived rules, each overridable via thresholds: venue = ≥5 check-ins OR visits spanning ≥3 distinct months (ranked by check-ins); brewery = ≥5 beers had AND avg rating ≥3.75, OR ≥15 beers (ranked by count blended with rating); beer = rated ≥4.25 OR had ≥3 times. Derived favorites are only as complete as the syncs behind them (untappd_sync_user_venues, untappd_sync_user_beers); "untappd" ones as the last untappd_sync_brewery_likes (freshness.brewery_likes). Filter by kind and source. Omit username for your own account.

Verify Untappd connectivity and that credentials are configured and can log in. Performs a lightweight authenticated request (your recent feed) and reports whether it succeeded, plus the running server version and the exact set of tools this build exposes (count, a stable hash, and their names) so you can confirm which build is live. Read-only.

Get recent check-ins near a location (lat/lng) — what people are drinking nearby right now. Optionally widen the search radius. Read-only.

One call from a tap list to "order this": give the raw menu lines as read from a photo and get back the top-rated beers the user has NOT had. It (1) refreshes the user's distinct-beers cache — an incremental refresh when the cache is complete, otherwise it backfills automatically within api_budget, no separate sync needed; (2) resolves each line to an Untappd beer (prices/punctuation stripped, scored on brewery + name match and check-in volume, venue_city as tie-breaker; resolutions are cached locally so repeat venues are instant); (3) treats "<Brewery> SEASONAL/ROTATING" as a list of possible beers (needs_confirmation) and "ROTATING CIDER"-style lines as unresolved ("ask bartender"); (4) checks every beer against the cache; (5) ranks the not-had ones by global rating. Returns picks, not_had, had, possible, unresolved, a sync block (what the refresh did) and freshness (coverage); if coverage is still incomplete a "not had" may be a false negative and another_run_needed is true. api_budget is also capped to the quota Untappd reports, when it reports one. Omit username for your own account.

Get your Untappd notifications — toasts, comments, friend requests, and badges earned on YOUR account, plus news items. Read-only.

Resolve an untappd.com URL AND fetch the entity detail in one call — the convenience combination of untappd_resolve + the matching info tool. Returns { resolved, detail }. Read-only.

Get the incoming friend requests waiting on YOUR account — the users who have requested to be your friend. Read-only.

Rejects/ignores an incoming friend request (see untappd_pending_friends for pending uids). Acts on YOUR account and affects a real relationship with another person. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Note: this endpoint path is taken from the Untappd app but is not otherwise independently verified.

Removes an existing friend, or cancels a friend request you sent. Acts on YOUR account and affects a real relationship with another person. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). Note: this endpoint path is taken from the Untappd app but is not otherwise independently verified.

Parse an untappd.com URL (a beer /b/, brewery /w/, venue /v/, user /user/, or check-in link) into its entity type and id, and name the tool to call next. Pure local parsing — no network. Read-only.

Search Untappd for beers by name (optionally "Brewery Beer"). Returns ranked matches with their beer id (bid), brewery, style, ABV, IBU, and global rating. Feed a bid into untappd_beer_info for full detail. Read-only.

Search Untappd for breweries by name. Returns matches with their brewery id, location, type, and beer count. Feed a brewery id into untappd_brewery_info for full detail. Read-only.

Search Untappd for venues (bars, breweries, restaurants) by name. Returns matches with their venue id, category, and location. Feed a venue id into untappd_venue_info for full detail. Read-only.

Mirror the breweries a user "likes" on Untappd (user/brewerylikes — the app calls them "followings"; works for other users' public/friend accounts) into the local cache. Liked breweries then count as favorites with source "untappd" — in untappd_favorites_list, the `favorite` field on has_had / brewery_beers / venue_menu / top_not_had / trip_check results, and the prefer_favorites boost. Each sync is a full pass from the top (~50 breweries per call), adding new likes and — once the pass finishes — dropping unliked ones (a partial pass never deletes). Resumable: saves progress every page; run again until another_run_needed is false (reports cached/total and percent). Stops BEFORE the ~100 calls/hour rate limit (or cleanly on a 429) with stopped_for_rate_limit and rate_limit.resume_at. Only reads Untappd. Untappd has NO followed/favorite VENUE list, so venue favorites stay derived + manual. (brewery/info's follow_status is the signed-in account's, never another user's — this list is the way to see theirs.) Omit username for your own account.

Fetch a user's detailed check-ins (venue, date, comment) into the cache from user/checkins. Incremental and resumable: pages backwards up to max_pages per call, persisting progress every page; run again until another_run_needed is false. NOTE: Untappd only returns the ~50 most recent check-ins for accounts other than your own and will not page further — such a sync reports history_truncated and you should use untappd_sync_user_beers for full has-had coverage. backfill_complete is only reported once ~all of total_checkins is cached. Pass force_backfill: true to reset a cache wrongly marked complete and re-page the whole history (cached rows are kept). Stops BEFORE the ~100 calls/hour rate limit (or cleanly on a 429) with stopped_for_rate_limit and rate_limit.resume_at — progress is saved; re-run after that time. Omit username for your own account.

Fetch a user's COMPLETE distinct-beers list (every unique beer they've ever had, with their rating, times-had count, and first/last dates) into the cache from user/beers. This is the cheapest way to get full "has had" coverage — thousands of beers instead of tens of thousands of check-ins — and, unlike user/checkins, it pages fully for any public/friend account. Offset-paged and resumable: fetches max_pages per call and persists progress; run again until another_run_needed is false. Feeds the same untappd_cache_has_had / has_had_many / not_had tools. Stops BEFORE the ~100 calls/hour rate limit (or cleanly on a 429) with stopped_for_rate_limit and rate_limit.resume_at — progress is saved; re-run after that time. Omit username for your own account.

Fetch a user's COMPLETE venue history (every venue they've checked in at, with first/most-recent visit dates and visit count) into the cache from user/venues. Unlike user/checkins — which only returns the ~50 most recent check-ins for anyone but yourself — user/venues pages any public/friend account's whole history, so this is how to answer "has this person been here?" (via untappd_cache_has_visited). Untappd serves 25 venues per page, so a 2,700-venue history is ~110 calls: resumable — fetches max_pages per call, saves progress after every page; run again until another_run_needed is false. Once complete, a re-run is a cheap refresh from the top that stops at the first page with no changed visits (a refresh cut short resumes where it stopped; another_run_needed stays true until it finishes). Stops BEFORE the ~100 calls/hour rate limit (or cleanly on a 429) with stopped_for_rate_limit and rate_limit.resume_at. Omit username for your own account.

OPT-IN, costs API calls: for a user's cached venue history (run untappd_sync_user_venues first), fetch the FIRST and MOST-RECENT visit check-ins of each venue via checkin/view (works for any public check-in) and cache the beer + date — a PARTIAL "what did they drink there" (two check-ins per venue at most, never the full list). One call per check-in, most-visited venues first, at most max_calls per run (default 10, max 50); already-cached check-ins are never re-fetched, and deleted/private ones (404) are remembered and skipped. Narrow with venue_ids and which. Stops BEFORE the ~100 calls/hour rate limit (or cleanly on a 429) with stopped_for_rate_limit and rate_limit.resume_at; run again until another_run_needed is false. Results appear in untappd_cache_has_visited under matches[].drinks. Stores only beer, brewery and date — never comments. Omit username for your own account.

Mirror a user's Untappd wishlist (user/wishlist) into the local cache, so pick tools can boost wishlisted beers without an API call. Each sync is a full pass from the top (~25 beers per call; wishlists are small), adding new beers and — once the pass finishes — dropping ones no longer wishlisted (a partial pass never deletes). Resumable: saves progress every page; run again until another_run_needed is false. Stops BEFORE the ~100 calls/hour rate limit (or cleanly on a 429) with stopped_for_rate_limit and rate_limit.resume_at. Only reads Untappd — never changes the wishlist (that is untappd_wishlist_add / _remove). Omit username for your own account; another user's wishlist needs a public account or friendship.

Toast (like) a check-in on YOUR account. This endpoint is a TOGGLE: calling it on a check-in you have already toasted removes the toast. Writes to your Untappd account and is visible to others. Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).

The "what should I order off this tap list?" tool. From a list of candidate beer ids, return the top N the user has NOT yet had, ranked by Untappd global rating, with an optional style filter. Not-had filtering uses the cache only (both sources, no API call). Beer ratings/styles come from a metadata cache; a beer/info API call is made only on a cache miss or if the cached metadata is >30 days old, capped at api_budget calls per run (~100 calls/hour limit) — if more are needed it returns partial: true / another_run_needed: true, so re-running fills the rest. A beer whose refresh is deferred or fails is still ranked on its older cached metadata and marked stale: true. Reports the same freshness/caveat block as untappd_cache_not_had. Omit username for your own account. For a GROUP pass usernames: mode "none_had" (default) ranks only beers new to everyone, "any_not_had" ranks beers at least one of them still needs (each ranked beer lists not_had_by / had_by). prefer_favorites (default true) lifts wishlisted beers (+0.5) and beers from a favorite brewery (+0.25) — liked on Untappd, derived or manual, any user's in a group; the wishlist needs untappd_sync_wishlist and Untappd likes untappd_sync_brewery_likes — and says so per beer (score, boosted_by, wishlisted, brewery_favorite/favorite).

Get the beers trending on Untappd right now, split into macro (big/widely-available) and micro (craft/independent) lists. Read-only.

Plan a brewery/bar crawl in ONE call: for each place (venue_id, name + city/state, lat/lng, and/or brewery_id) return whether the user has been there (dates, total visits, matched venues incl. "(duplicate of …)" copies — from the cached venue history, run untappd_sync_user_venues first), and for a brewery_id: how many of its beers they have had and the top 4 (top_n) NOT-had beers by Untappd global rating, optionally filtered by style (out-of-production beers skipped unless include_out_of_production). Has-had and visits come from the cache ONLY; the only API calls are brewery/beer_list fetches for a brewery whose list is not cached or is past its 7-day TTL, at most api_budget (default 5; 0 = strictly cache-only, a stale list is then used and flagged) under the ~100 calls/hour guard — a missing list sets another_run_needed. Beer lists are global facts: Untappd's have_had on that endpoint is the AUTHENTICATED account's and is never used. Favorites (breweries liked on Untappd via untappd_sync_brewery_likes, derived from the cached history, or added with untappd_favorite_add) are flagged on matched venues, the brewery and beers; prefer_favorites (default true) lifts wishlisted beers (+0.5) and a favorite brewery's beers (+0.25); and a stop within near_favorite_radius_m (default 2000 m) of a favorite venue gets near_favorites + a "Near a favorite" hint. For a GROUP pass usernames + mode ("none_had" default / "any_not_had"). Returns has-had and venue freshness blocks.

Get the badges a user has earned, most recent first. Omit username for your own account. Read-only.

Get the distinct (unique) beers a user has ever checked in, with their rating and check-in count per beer. Supports sorting and paging. Omit username for your own account. Read-only.

Get a user's recent check-ins (most recent first): the beer, rating, comment, venue, and toasts/comments. Page backwards with max_id (the pagination.max_id from a prior call). Only your OWN history pages fully: for any other user Untappd returns just the ~50 most recent check-ins and ignores max_id — use untappd_user_beers (has had) or untappd_user_venues (has been) for their full history. Omit username for your own. Read-only.

Get a user's friend list. Omit username for your own account. Read-only.

Get an Untappd user's profile: bio, location, total check-ins, distinct beers, badges, and stats. Omit username for your own account. Read-only.

Get the venues a user has checked in at, most recent first, with per-venue first/recent visit and check-in counts. Pages fully for any public/friend account (unlike user check-ins, which stop at ~50 for other users). Untappd returns at most 25 venues per page whatever limit you ask for — advance by the returned pagination offset. Omit username for your own account. Read-only.