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_id and client_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_search first to resolve a venue name to an ID.
• Public check-ins only — private user accounts are not visible.

License

MIT