Skip to main content
Glama
untappd-mcp

untappd-mcp

by chrischall

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.

Related MCP server: Polvenn MCP Server

Configuration

Variable

Required

Description

UNTAPPD_ACCESS_TOKEN

no

An access token you already hold. Supply this and no password is needed — the xauth login is skipped entirely.

UNTAPPD_USERNAME

if no token

Your Untappd username or login email.

UNTAPPD_PASSWORD

if no token

Your Untappd password (used only for the xauth login that mints a token).

UNTAPPD_CLIENT_ID

for login & writes

The Untappd mobile app client id (see below). A pre-seeded access token can read without it.

UNTAPPD_CLIENT_SECRET

for login & writes

The Untappd mobile app client secret.

UNTAPPD_DEVICE_ID

no

Stable device UUID the token is keyed to (a default is provided).

UNTAPPD_UTV

no

API version param (default 4.0.0).

UNTAPPD_USER_AGENT

no

Override the User-Agent (default mimics the app).

UNTAPPD_TIMEZONE

no

IANA timezone (e.g. America/New_York) that check-ins are stamped with when the call doesn't pass timezone. Set it when the server runs somewhere other than the drinker's zone (e.g. a hosted connector, usually UTC). Defaults to the server process's zone.

UNTAPPD_PHOTO_DIR

no

The directory untappd_checkin's photo_path must be inside (several allowed, separated by :). Defaults to ~/Downloads/untappd-mcp — put a photo there to attach it. Any other file is refused, so a prompt-injected shout or comment can't publish an arbitrary image from your disk.

UNTAPPD_CACHE_DB

no

Path to the local check-in cache SQLite file (default ~/.untappd-mcp/checkins.db). A relative path or leading ~ resolves against your home directory, never the working directory, so every host (Claude Desktop, Claude Code, …) finds the same file; the resolved path is logged to stderr at startup. The db file is always made owner-only (0600), and so are any directories the server creates plus the default ~/.untappd-mcp; a directory you point this into that already exists keeps its permissions. Local/stdio only.

UNTAPPD_CACHE_DIR

no

Directory for the cache instead of ~/.untappd-mcp (the file is checkins.db inside it). UNTAPPD_CACHE_DB wins if both are set.

UNTAPPD_RATE_LIMIT_PER_HOUR

no

The hourly call limit the syncs' stop-before-429 guard enforces (default 100, Untappd's documented per-token limit). Only change it if Untappd gives your token a different limit.

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.

variable

default

MCP_CONFIRM_MODE

ask-user

What a write does on a client that cannot show a confirmation prompt (claude.ai, Claude Desktop). ask-user: two steps — the first call does nothing and returns a preview plus a token, and the model must get your approval in chat before calling again with it. auto: the same two steps, but the model may use the token after reviewing the preview itself. refuse: writes are refused on such clients. A client that can show prompts (Claude Code) always gets the real prompt, unless MCP_CONFIRM_ELICITATION=off. An unrecognised value is treated as refuse.

MCP_CONFIRM_ELICITATION

on

off never shows a confirmation prompt, so every client gets the MCP_CONFIRM_MODE behaviour. Set it for a client that says it can show prompts but never does (the write hangs — opencode 2.0.x). Any other value is treated as on, with a warning on stderr.

MCP_CONFIRM_TTL_SECONDS

600

How long a token stays valid.

MCP_CONFIRM_SECRET

random per process

Signing key; set it only if tokens must survive a server restart.

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 pass finishes. Liked breweries then carry the source untappd everywhere favorites appear — merged with derived and manual, each source listed once — and count for the prefer_favorites boost and trip_check's flags. untappd_cache_status reports each user's brewery_likes coverage, and untappd_cache_forget removes them.

Untappd has no followed or favorite venue list at all (no web or API route; venue/info has no per-user flag), so venue favorites are derived + manual only. brewery/info's claimed_status.follow_status describes the signed-in account, like have_had below, so it is never used for anyone else — the synced likes list is how to see another user's.

Cached reads (to stretch the ~100 calls/hour limit): untappd_brewery_beers keeps each brewery's list for 7 days, and untappd_venue_menu / untappd_venue_activity keep results for 6 hours; each reports where the answer came from and takes refresh: true to re-fetch. Untappd's have_had on a brewery's beer list describes the signed-in account, never the user you're asking about, so it isn't cached or returned — use untappd_cache_has_had_many for any user.

Menu picks: untappd_menu_pick (tap-list lines in, ranked not-had beers out), untappd_venue_pick (same, from a venue's Untappd menu).

Picking a beer off a menu

untappd_menu_pick turns "find Mer a beer" from a menu photo into one call. Give it the lines as read off the board:

{
  "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
}

In one call it:

  1. Freshens the cache. If the user's distinct-beers list is already complete it does an incremental refresh, stopping at the first beer that's cached and unchanged (usually one page). If the list is empty or partial it backfills in the same call until done or api_budget (default 60 calls, shared by every step) runs out. You never need to call a sync tool first.

  2. Resolves each line to a beer. It strips prices, sizes, ABV and punctuation, searches Untappd (falling back to a query without the style word, because Untappd search matches every term), and scores the candidates on brewery match, beer-name match (so "Homestyle" isn't read as "Double Homestyle"), check-in volume (the canonical entry wins over a 3-check-in duplicate) and venue_city. Up to 4 searches run at once, and a 429 is retried with backoff. Resolutions are cached on disk, so the next visit to the same venue costs no searches.

  3. Handles generic lines. <Brewery> SEASONAL / ROTATING becomes a possible list of that brewery's seasonal-looking beers, marked needs_confirmation. A line with no brewery (ROTATING CIDER) comes back unresolved: "ask bartender".

  4. Checks every beer against the cache (both sources, as has_had_many does).

  5. Ranks the not-had beers by global rating, applies style_filter, and returns the top top_n as picks.

Output for the call above, with Mer having had Fennario (abridged: not_had also lists the Tennessee Lager at 3.33, possible lists six candidates, and a freshness block is appended):

{
  "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 says what the refresh did; coverage lives in freshness. If the budget runs out before the backfill finishes, freshness.coverage_complete is false, another_run_needed is true, and the freshness caveat warns that a "not had" may be a false negative. Calling again continues from where it stopped.

Quota. When an Untappd response carries X-Ratelimit-Remaining, the server remembers it for the hour, and every budgeted tool (menu_pick, venue_pick, top_not_had, both syncs) caps its budget to what's left. The result then includes quota_remaining, plus budget_clamped_to_quota: true when the cap applied. Untappd's public API documents the header; if the private API this server uses doesn't send it, budgets work exactly as before.

untappd_venue_pick takes an Untappd venue URL (https://untappd.com/v/<slug>/<id>) or id instead of items. It pages through the venue's whole verified menu, takes the venue's city from it, and runs the same check and ranking. Menu items already carry beer ids, so there is no search step.

Check-in cache

The Untappd API only exposes paged lists (50 per page) and has no "has this user ever had beer X?" lookup — answering that from the API alone means paging an entire history (often 11k+ check-ins) against a tight ~100-calls/hour rate limit. These tools maintain a SQLite mirror so the question is answered instantly, offline, with zero API calls. The mirror is a local SQLite file (node:sqlite, default ~/.untappd-mcp/checkins.db, overridable with UNTAPPD_CACHE_DB / UNTAPPD_CACHE_DIR). The store is injectable, so another deployment can back it differently without the tools changing.

Persistence. The file survives restarts, and a backfill that was cut off (rate limit, crash, host quit) resumes from its saved offset on the next sync. The file runs in WAL mode with a busy timeout and does every write in a transaction, so two hosts open at the same time can share it. The schema is versioned (PRAGMA user_version) and only ever migrated forward, adding columns and tables, so an upgrade never wipes it. untappd_cache_status shows the resolved path, size, schema version and per-user coverage.

Two sync sources fill the cache:

  • untappd_sync_user_beers pages user/beers — the user's complete distinct-beers list (thousands of rows, not tens of thousands of check-ins). This is the cheapest way to get full "has had" coverage and, unlike user/checkins, it pages fully for any public/friend account. Start here for has-had questions.

  • untappd_sync_checkins pages user/checkins for detailed check-ins (venue, date, comment). Only your own account pages fully — Untappd returns just the ~50 most recent for anyone else and won't page further, which the tool reports as history_truncated (it never falsely claims backfill_complete). Pass force_backfill: true to reset a cache wrongly marked complete and re-page from newest (cached rows are kept). Use this for recent venue/date detail; use untappd_sync_user_beers for coverage.

Both are resumable: they fetch max_pages per call (default 10), persist progress after every page, and set another_run_needed: true until done — just call again until it's false.

Rate limit. Every API response is recorded (time, status and any X-Ratelimit-* / Retry-After headers) and, once the cache is open, logged in the cache file so every process sharing it — and the next one — counts the same hour. The syncs check that count before every page and stop cleanly with stopped_for_rate_limit: true and rate_limit.resume_at when the next call would leave fewer than 2 of the ~100 hourly calls; a 429 that slips through also stops the run cleanly instead of failing it. Progress is already saved, so re-run after resume_at. untappd_cache_status shows the current picture under rate_limit. Note: the v4 API sends X-Ratelimit-Remaining: 0 on every successful response, so that header is ignored until it reports a live (non-zero) value; the estimate rests on the local call count.

Query the cache with no further API calls. The has-had tools consult both sources (a hit in either counts as had):

  • untappd_cache_has_had — has the user had a beer, by exact bid or a case-insensitive beer_name substring; returns count, best rating, last date, matching sources, and any detailed check-ins.

  • untappd_cache_has_had_many — cross-check a whole list of bids in one call (e.g. a venue's menu) → had/not-had per beer.

  • untappd_cache_not_had — given a list of bids, return just the ones the user has not had — the "what's new to me on this menu?" filter.

  • untappd_top_not_had — from a list of bids, return the top N not-had beers ranked by Untappd global rating, with an optional style filter (the "what should I order off this tap list?" tool). Not-had filtering is cache-only; beer ratings come from a metadata cache (beer_meta) that's seeded opportunistically by untappd_beer_info / untappd_search_beer and topped up via beer/info only on a cache miss or entries older than 30 days — capped at api_budget calls/run (default 25), returning partial: true / another_run_needed: true when more are needed.

  • untappd_cache_query — filter cached check-ins by brewery, style, min_rating, venue, and/or date range, with sorting and a limit.

Every read result carries a freshness block that reports each source's completeness separately (checkins.backfill_complete / history_truncated, beers.complete, per-source percentages) plus coverage_complete, and a caveat while coverage is incomplete — so a "not found" can be flagged as possibly a false negative until the relevant sync finishes.

Syncing another user goes through the same authed endpoint as untappd_user_checkins, so Untappd's privacy rules apply: it only works if that account is public or your friend. Otherwise the sync returns a clear error telling you to add them as a friend first.

Retention. Nothing in the cache expires: synced rows — including another user's dated check-ins, comments and venues — stay until you remove them. The file is created owner-only (directory 0700, database 0600, and older installs are tightened on open). untappd_cache_forget deletes one user's cached check-ins, distinct-beers list, venue history, wishlist copy, liked breweries, local favorites, venue drinks and sync state after a confirmation (preview shows the username and row counts); it touches only the local cache, never Untappd, and a later sync can re-fetch. Deleting the file removes everything.

A cache holds only the check-ins the account it belongs to was allowed to fetch. untappd_healthcheck reports the running version and the exact tool set (count + names + a stable hash), so you can confirm which build is serving.

Development

npm install
npm run build
npm test

License

MIT

Available Tools

59 tools
untappd_accept_friendAccept an Untappd friend requestA
DestructiveIdempotent

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.

Inputs: target_uid (required), confirmToken.

untappd_activity_feedGet Untappd friend activity feedA
Read-only

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.

Inputs: view, limit, max_id.

untappd_add_commentComment on an Untappd check-inA
Destructive

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).

Inputs: comment (required), checkin_id (required), confirmToken.

untappd_add_friendSend an Untappd friend requestA
DestructiveIdempotent

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.

Inputs: target_uid (required), confirmToken.

untappd_beer_activityGet recent check-ins for a beerA
Read-only

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.

Inputs: bid (required), view, limit, max_id.

untappd_beer_infoGet Untappd beer detailA
Read-onlyIdempotent

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.

Inputs: bid (required), view.

untappd_brewery_beersGet a brewery's beer listA
Read-onlyIdempotent

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.

Inputs: brewery_id (required), sort, view, limit, +3 more.

untappd_brewery_infoGet Untappd brewery detailA
Read-onlyIdempotent

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").

Inputs: brewery_id (required), view.

untappd_cache_forgetForget a user's cached check-insA
DestructiveIdempotent

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).

Inputs: username, confirmToken.

untappd_cache_has_hadCheck if a user has had a beer (from the cache)A
Read-onlyIdempotent

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.

Inputs: bid, username, beer_name.

untappd_cache_has_had_manyBatch-check many beers against the cacheA
Read-onlyIdempotent

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.

Inputs: bids (required), mode, username, usernames.

untappd_cache_has_visitedCheck if a user has been to a venue (from the cache)A
Read-onlyIdempotent

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.

Inputs: queries (required), username, max_matches.

untappd_cache_not_hadFrom a list of beers, return the ones a user has NOT hadA
Read-onlyIdempotent

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.

Inputs: bids (required), username.

untappd_cache_queryQuery cached check-ins with filtersA
Read-onlyIdempotent

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.

Inputs: sort, limit, style, venue, +7 more.

untappd_cache_statusShow the local cache location, schema and per-user coverageA
Read-onlyIdempotent

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.

Inputs: no named parameters.

untappd_checkinCheck in a beer on UntappdA
Destructive

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 ONE photo (JPEG/PNG, max 15 MB) via exactly one of photo_path (a local file), photo_inline (base64, for a small photo) or photo_blob_key. On the hosted connector, use the slot flow: call untappd_upload_slots, PUT the photo with the returned curl, then pass its blobKey as photo_blob_key (a path cannot work there). 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).

Inputs: bid (required), shout, geolat, geolng, +8 more.

untappd_checkin_infoGet Untappd check-in detailA
Read-onlyIdempotent

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.

Inputs: checkin_id (required).

untappd_delete_checkinDelete an Untappd check-inA
DestructiveIdempotent

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).

Inputs: checkin_id (required), confirmToken.

untappd_delete_commentDelete a comment from an Untappd check-inA
DestructiveIdempotent

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).

Inputs: comment_id (required), confirmToken.

untappd_favorite_addMark a beer, brewery or venue as a favorite (local)A
Idempotent

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.

Inputs: id (required), kind (required), note, username.

untappd_favorite_removeRemove a manual favorite (local)A
Idempotent

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.

Inputs: id (required), kind (required), username.

untappd_favorites_listList a user's favorite beers, breweries and venuesA
Read-onlyIdempotent

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: "). 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.

Inputs: kind, limit, source, username, +1 more.

untappd_healthcheckUntappd healthcheckA
Read-onlyIdempotent

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.

Inputs: no named parameters.

untappd_local_checkinsGet nearby Untappd check-insA
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.

Inputs: lat (required), lng (required), view, limit, +1 more.

untappd_menu_pickPick beers off a tap list that a user hasn't hadA

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 " 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.

Inputs: items (required), top_n, username, api_budget, +3 more.

untappd_notificationsGet your Untappd notificationsA
Read-only

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

Inputs: limit, offset.

untappd_open_urlOpen an Untappd URL (resolve + fetch)A
Read-onlyIdempotent

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.

Inputs: url (required).

untappd_pending_friendsGet your pending friend requestsA
Read-onlyIdempotent

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

Inputs: limit, offset.

untappd_reject_friendReject an Untappd friend requestA
DestructiveIdempotent

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.

Inputs: target_uid (required), confirmToken.

untappd_remove_friendRemove an Untappd friendA
DestructiveIdempotent

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.

Inputs: target_uid (required), confirmToken.

untappd_resolveResolve an Untappd URLA
Read-onlyIdempotent

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.

Inputs: url (required).

untappd_search_beerSearch Untappd beersA
Read-onlyIdempotent

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.

Inputs: query (required), sort, view, limit, +1 more.

untappd_search_brewerySearch Untappd breweriesA
Read-onlyIdempotent

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.

Inputs: query (required), limit, offset.

untappd_search_venueSearch Untappd venuesA
Read-onlyIdempotent

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.

Inputs: query (required), limit.

untappd_sync_brewery_likesSync a user's liked (followed) breweries into the cacheA

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.

Inputs: username, max_pages.

untappd_sync_checkinsSync a user's check-ins into the cacheA

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.

Inputs: username, max_pages, force_backfill.

untappd_sync_user_beersSync a user's complete distinct-beers list into the cacheA

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.

Inputs: username, max_pages.

untappd_sync_user_venuesSync a user's complete venue history into the cacheA

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.

Inputs: username, max_pages.

untappd_sync_venue_drinksFetch what a user drank on their first/latest visit to each venue (opt-in)A

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.

Inputs: which, username, max_calls, venue_ids.

untappd_sync_wishlistSync a user's wishlist into the cacheA

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.

Inputs: username, max_pages.

untappd_toastToast an Untappd check-inA
Destructive

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).

Inputs: checkin_id (required), confirmToken.

untappd_top_not_hadTop-rated beers a user has NOT had, from a candidate listA

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).

Inputs: bids (required), mode, style, top_n, +4 more.

untappd_trip_checkCheck a list of trip stops against a user’s history (cache)A
Read-onlyIdempotent

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.

Inputs: places (required), mode, style, top_n, +7 more.

untappd_upload_slotsGet upload URLs for Untappd check-in photosA
Read-only

Get signed upload URLs for check-in photos — the way to attach a photo on the HOSTED connector, which cannot read files on your machine. For each photo (JPEG or PNG, max 15 MB) it returns a blobKey and a ready curl command: run the curl with the path to the photo (it must send exactly the returned Content-Type), then pass the blobKey to untappd_checkin as photo_blob_key. URLs expire after 30 minutes. Posts nothing to Untappd. Only available where the deployment provides a blob store; on a local install use photo_path or photo_inline.

Inputs: slots (required).

untappd_user_badgesGet Untappd user badgesA
Read-onlyIdempotent

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

Inputs: limit, offset, username.

untappd_user_beersGet Untappd distinct beersA
Read-onlyIdempotent

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.

Inputs: sort, view, limit, offset, +1 more.

untappd_user_checkinsGet Untappd user check-insA
Read-onlyIdempotent

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.

Inputs: view, limit, max_id, username.

untappd_user_friendsGet Untappd user friendsA
Read-onlyIdempotent

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

Inputs: limit, offset, username.

untappd_user_infoGet Untappd user profileB
Read-onlyIdempotent

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

Inputs: view, username.

untappd_user_venuesGet venues a user has checked in atA
Read-onlyIdempotent

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.

Inputs: sort, limit, offset, username.

untappd_user_wishlistGet Untappd user wishlistA
Read-onlyIdempotent

Get the beers on a user's wishlist. Supports sorting and paging. Omit username for your own account. Read-only.

Inputs: sort, view, limit, offset, +1 more.

untappd_venue_activityGet recent check-ins at a venueA
Read-only

Get the recent public check-ins at a venue by its id — who was there, what they drank, and their ratings. Page backwards with max_id (the pagination.max_id from a prior call). Cached locally for 6 hours per venue + limit + max_id (cache.hit, fetched_at, expires_at); refresh:true re-fetches. Read-only.

Inputs: venue_id (required), view, limit, max_id, +1 more.

untappd_venue_by_foursquareLook up an Untappd venue by Foursquare idA
Read-onlyIdempotent

Resolve a Foursquare venue id to its Untappd venue. Useful to turn a foursquare_id (e.g. from a check-in) into an Untappd venue you can pass to untappd_venue_info / untappd_venue_activity. Read-only.

Inputs: foursquare_id (required).

untappd_venue_infoGet Untappd venue detailA
Read-onlyIdempotent

Get full detail for a venue by its Untappd venue id: category, address, contact, rating, total check-ins, and — on view:"full" — top beers and recent activity. Get an id from untappd_search_venue. Read-only.

Inputs: venue_id (required), view.

untappd_venue_menuGet a venue's verified beer menu (section-paged)A
Read-onlyIdempotent

Return a venue's verified beer menu as a flat, compact list of beers. untappd_venue_info returns only the FIRST section of each menu (Untappd defaults the section list to one), so it silently under-reports any venue whose menu spans multiple sections — e.g. a 23-beer wall that comes back with 2 items. This tool forwards the section_limit / section_offset paging params venue/info echoes back but never receives, walks sections up to a per-call max_pages budget (respecting the ~100 calls/hour limit — it does NOT loop to completion in one call), and flattens to [{bid, name, brewery, brewery_id, style, abv, price, serving_type, menu, section}]. Like the sync tools it is resumable: when the budget runs out before full coverage it returns another_run_needed:true plus next_section_offset to pass back on the next call. truncated:true means the upstream returned no more sections short of total_count (e.g. it ignored the paging params) — not resumable. Results are cached locally for 6 hours per venue + paging params (cache.hit, fetched_at, expires_at) so repeated trip planning does not re-spend calls; refresh:true re-fetches. With the cache, the result also carries favorite {is_favorite, sources, reason} for the venue, and favorite / brewery_favorite on each beer that is one (derived from username's history or added with untappd_favorite_add; default your account) — applied on read, so never stale. Get an id from untappd_search_venue. Read-only.

Inputs: venue_id (required), sort, menu_id, refresh, +4 more.

untappd_venue_pickPick beers off a venue's Untappd menu that a user hasn't hadA

Like untappd_menu_pick, but takes an Untappd venue (URL or id) instead of menu lines: it pulls the venue's FULL verified menu (walking every section page until complete, within api_budget), refreshes the user's distinct-beers cache (incremental, or an automatic backfill), checks every menu beer against it and ranks the not-had ones by global rating. Returns the same picks / not_had / had / sync shape plus a venue block (menu_complete is false only if the budget ran out mid-menu). A venue with no verified menu comes back unresolved — use untappd_menu_pick with the tap list instead. Omit username for your own account.

Inputs: venue (required), top_n, username, api_budget, +1 more.

untappd_wishlist_addAdd a beer to your wishlistA
Idempotent

Add a beer to YOUR Untappd wishlist by its bid. Writes to your 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).

Inputs: bid (required), confirmToken.

untappd_wishlist_removeRemove a beer from your wishlistA
Idempotent

Remove a beer from YOUR Untappd wishlist by its bid. Writes to your 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).

Inputs: bid (required), confirmToken.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 59 tools

    Disambiguation2/5

    The set has many overlapping clusters: venue_info/venue_menu/venue_activity/venue_pick, brewery_info/brewery_beers, beer_info/beer_activity, user_checkins/user_beers/user_venues vs their sync_* counterparts, and multiple has-had/pick tools (cache_not_had, cache_has_had, cache_has_had_many, top_not_had, menu_pick, venue_pick, trip_check). Descriptions are detailed, but the sheer number of specialized variants makes misselection likely.

    Naming Consistency3/5

    All names use snake_case with the untappd_ prefix, which keeps them readable. However, conventions are mixed: some are verb-first (add_comment, search_venue, sync_checkins, cache_has_had) while many are entity-first (venue_info, brewery_beers, wishlist_add, checkin_info, cache_status).

    Tool Count1/5

    59 tools is far beyond the typical 3-15 well-scoped range and beyond the 25+ threshold for an overly heavy surface. The large number of cache, sync, pick, info, and activity variants makes the server difficult to navigate as a single coherent tool set.

    Completeness4/5

    The surface covers most Untappd workflows: search/info/activity for beers, breweries, venues, users, and check-ins; check-in creation/deletion; comments; toasts; friends; wishlist; favorites; notifications; badges; feeds; and extensive cache/sync/pick support. Minor gaps remain, such as no user-search tool and no update operations, but core workflows are workable.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for Android's Tasker automation app
      52
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A local-first MCP server for tracking beer releases on Vinmonopolet, enabling users to search new and upcoming beers, check store stock, find nearby stores, and manage watchlists.
      8
      21 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A Node.js MCP server for X/Twitter that enables user profile queries, tweet search, tweet detail retrieval, and media downloads (images, videos, GIFs) via X's Web GraphQL API.
      6
      2
      ISC