untappd-mcp-server
A Model Context Protocol (MCP) server that exposes the Untappd API as tools for AI agents. Search for venues, breweries, and beers, check what's on tap via recent check-in feeds, and look up user activity — all from any MCP-compatible client.
Prerequisites
- Node.js 18+
- Untappd API credentials (
client_idandclient_secret) from untappd.com/api
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"
}
}
}
}
Tools
venue_search
Search for venues (breweries, bars, restaurants) by name with optional location awareness.
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Search query (venue name) |
lat | number | No | Latitude for location-aware results |
lng | number | No | Longitude for location-aware results |
get_venue_info
Retrieve detailed information and recent check-ins for a venue.
| Parameter | Type | Required | Description |
|---|---|---|---|
venue_id | integer | Yes | Untappd venue ID |
compact | boolean | No | If true, returns venue info only (no checkins, media, top beers) |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
venue_id | integer | Yes | Untappd venue ID |
limit | integer | No | Number of results (max 25, default 25) |
max_id | integer | No | Return results older than this checkin ID |
min_id | integer | No | Return only checkins newer than this ID |
search_brewery
Search for breweries by name.
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Brewery name search query |
offset | integer | No | Offset for pagination |
get_brewery_info
Retrieve detailed information, beer list, and recent check-ins for a brewery.
| Parameter | Type | Required | Description |
|---|---|---|---|
brewery_id | integer | Yes | Untappd brewery ID |
compact | boolean | No | If true, returns brewery info only |
search_beer
Search for beers by name.
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Beer name search query |
offset | integer | No | Pagination offset |
sort | string | No | Sort order: checkin (default), name, count |
get_beer_info
Retrieve detailed information for a specific beer.
| Parameter | Type | Required | Description |
|---|---|---|---|
bid | integer | Yes | Untappd beer ID |
compact | boolean | No | If true, returns beer info only |
get_user_info
Retrieve profile and stats for an Untappd user.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | Yes | Untappd username |
compact | boolean | No | If true, returns user info only (no checkins, media, recent brews) |
get_user_activity
Retrieve the recent check-in activity feed for a user.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | Yes | Untappd username |
limit | integer | No | Number of results (max 25, default 25) |
max_id | integer | No | Return results older than this checkin ID |
min_id | integer | No | Return only checkins newer than this ID |
Rate Limiting
The Untappd API allows 100 calls per hour per API key. Every tool response includes the current rate limit status:
{
"rateLimit": {
"limit": 100,
"remaining": 97
}
}
The server does not block requests at the rate limit — if the limit is exceeded, the Untappd API returns a 429 error which is surfaced as: Rate limit exceeded. Limit: 100, Remaining: 0. Resets hourly.
Authentication
This server uses client_id + client_secret authentication for public API endpoints. OAuth user authentication (access tokens) is not currently supported.
Set credentials via environment variables:
UNTAPPD_CLIENT_ID=your_client_id
UNTAPPD_CLIENT_SECRET=your_client_secret
The server will throw on startup if these are not set.
Development
npm install
npm run build
npm start
Testing with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
Known Limitations
- No tap list data — actual tap lists require an Untappd for Business subscription. Venue check-in feeds serve as a real-time proxy.
- Rate limit: 100/hour — minimise redundant calls; check-in feeds are the recommended approach for live data.
- Venue IDs required — use
venue_searchfirst to resolve a venue name to an ID. - Public check-ins only — private user accounts are not visible.
License
MIT