untappd-mcp-server

A Model Context Protocol (MCP) server that exposes the Untappd API as tools for AI agents — 27 tools covering the full Untappd v4 read API, plus built-in interactive OAuth authentication. Search venues, breweries, and beers; check what's on tap via check-in feeds; explore user badges, friends, wish lists, and drinking history; and aggregate stats — all from any MCP-compatible client.

Prerequisites

• Node.js 20+
• Untappd API credentials (client_id and client_secret) from untappd.com/api
• Optional: an Untappd OAuth access token to unlock authenticated tools — obtainable in-chat via the authenticate_untappd tool or npx untappd-mcp-server auth (see Interactive Authentication)

Quick Start

Via npx (zero install)

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

PowerShell

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

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

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

Tools

Tools marked 🔑 token require an access token (UNTAPPD_ACCESS_TOKEN env var or interactive authentication).

Authentication Tools

authenticate_untappd

Interactively authenticate with Untappd via OAuth: opens your browser to Untappd's approve page, captures the redirect on a temporary localhost listener, and saves the access token — the 🔑 tools work immediately, no restart. Prerequisite: your Untappd app's Callback URL must be set to exactly http://localhost:8737/callback (or your UNTAPPD_REDIRECT_URL).

get_auth_status

Report authentication status: token presence, source (env var or token file), file path, and whether the 🔑 tools are unlocked. Free by default; validate: true verifies the token with one API call.

Search & Lookup

venue_search

Search for venues (breweries, bars, restaurants) by name with optional location awareness.

search_brewery

Search for breweries by name.

search_beer

Search for beers by name.

Venue

get_venue_info

Retrieve detailed information and recent check-ins for a venue.

get_venue_checkins

Retrieve the recent check-in feed for a venue. This is the primary tool for determining what's currently on tap — recent check-ins act as a live signal for available beers.

get_venue_foursquare_lookup

Resolve a Foursquare venue ID to its Untappd venue — the bridge between Foursquare/location data and Untappd venue tools.

Beer

get_beer_info

Retrieve detailed information for a specific beer.

get_beer_checkins

Retrieve the recent public check-in feed for a specific beer — what people are saying about it right now, and where they're drinking it.

get_trending_beers

Retrieve globally trending beers (macro and micro brew lists, by recent check-in velocity). No parameters.

Brewery

get_brewery_info

Retrieve detailed information, beer list, and recent check-ins for a brewery.

get_brewery_checkins

Retrieve the recent public check-in feed for a brewery — all its beers being checked in globally.

User

get_user_info

Retrieve profile and stats for an Untappd user.

get_user_activity

Retrieve the recent check-in activity feed for a user.

get_user_distinct_beers

Retrieve the unique beers a user has checked in, with flexible sort ordering. sort=checkin with limit=1 is the single-call pattern for "most-checked-in beer".

get_user_wishlist

Retrieve beers on a user's wish list.

get_user_badges

Retrieve a user's earned badges (pages of 50, most recent first).

get_user_friends

Retrieve a user's friend list (public accounts only).

Activity Feeds

get_global_feed

Retrieve the global public check-in feed (The Pub). High rate-limit cost for the data returned — prefer min_id polling to fetch only new check-ins. Note: standard API keys are typically not authorized for /thepub — Untappd returns "You are not authorized to call this method from this key" unless your key has elevated access (get_local_feed is not restricted).