untappd

untappd-mcp-server

一个 Model Context Protocol（MCP）服务，将 Untappd API 封装为供 AI Agent 使用的工具——27 个工具涵盖完整的 Untappd v4 只读 API，并内置交互式 OAuth 身份验证。搜索场所、啤酒厂和啤酒；通过签到动态查看正在供应的啤酒；探索用户徽章、好友、愿望清单和饮酒历史；还可汇总统计数据——所有操作均可通过任何兼容 MCP 的客户端完成。

前置条件

• Node.js 20+
• Untappd API 凭据（client_id 和 client_secret），可从 untappd.com/api 获取
• 可选：Untappd OAuth 访问令牌，用于解锁需要身份验证的工具——可在聊天中通过 authenticate_untappd 工具获取，也可运行 npx untappd-mcp-server auth 获取（参见交互式身份验证）

快速开始

通过 npx（无需安装）

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

将以下内容添加到 Claude Desktop 配置文件（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"
      }
    }
  }
}

工具

标记为 🔑 token 的工具需要访问令牌（UNTAPPD_ACCESS_TOKEN 环境变量或交互式身份验证）。

身份验证工具

authenticate_untappd

通过 OAuth 与 Untappd 进行交互式身份验证：在浏览器中打开 Untappd 授权页面，在临时的 localhost 监听器上接收重定向，并保存访问令牌——🔑 工具可立即使用，无需重启。前置条件： Untappd 应用的 Callback URL 必须准确设置为 http://localhost:8737/callback（或你的 UNTAPPD_REDIRECT_URL）。

参数	类型	必填	说明
timeout_seconds	integer	否	等待浏览器授权的时长（默认值为 180，最大值为 600）

get_auth_status

报告身份验证状态：令牌是否存在、来源（环境变量或令牌文件）、文件路径，以及 🔑 工具是否已解锁。默认免费；validate: true 会通过一次 API 调用验证令牌。

参数	类型	必填	说明
validate	boolean	否	通过一次 API 调用验证令牌（默认值为 false）

搜索与查询

venue_search

按名称搜索场所（啤酒厂、酒吧、餐厅），并可选择结合位置信息。

参数	类型	必填	说明
q	string	是	搜索查询（场所名称）
lat	number	否	用于按位置筛选结果的纬度
lng	number	否	用于按位置筛选结果的经度

search_brewery

按名称搜索啤酒厂。

参数	类型	必填	说明
q	string	是	啤酒厂名称搜索查询
offset	integer	否	分页偏移量

search_beer

按名称搜索啤酒。

参数	类型	必填	说明
q	string	是	啤酒名称搜索查询
offset	integer	否	分页偏移量
sort	string	否	排序方式：checkin（默认）、name、count

场所

get_venue_info

获取场所的详细信息和近期签到记录。

参数	类型	必填	说明
venue_id	integer	是	Untappd 场所 ID
compact	boolean	否	若为 true，则仅返回场所信息（不包含签到、媒体和热门啤酒）

get_venue_checkins

获取某个场所最近的签到动态。这是判断当前在售啤酒的主要工具——最近的签到是反映在售啤酒的实时信号。

参数	类型	必填	描述
venue_id	integer	是	Untappd 场所 ID
limit	integer	否	结果数量（最多 25，默认值为 25）
max_id	integer	否	返回签到 ID 早于此 ID 的结果
min_id	integer	否	仅返回签到 ID 晚于此 ID 的结果

get_venue_foursquare_lookup

将 Foursquare 场所 ID 解析为对应的 Untappd 场所——连接 Foursquare/位置信息与 Untappd 场所工具的桥梁。

参数	类型	必填	描述
foursquare_id	string	是	v2 MD5 哈希格式的 Foursquare 场所 ID（v3 数字 ID 无法使用）

啤酒

get_beer_info

获取特定啤酒的详细信息。

参数	类型	必填	描述
bid	integer	是	Untappd 啤酒 ID
compact	boolean	否	如果为 true，则仅返回啤酒信息

get_beer_checkins

获取特定啤酒最近的公开签到动态——人们此刻如何评价它，以及他们在哪里饮用。

参数	类型	必填	描述
bid	integer	是	Untappd 啤酒 ID
limit	integer	否	每页结果数（最多 50，默认值为 25）
max_id	integer	否	返回签到 ID 早于此 ID 的结果
min_id	integer	否	仅返回签到 ID 晚于此 ID 的结果

get_trending_beers

获取全球热门啤酒（根据近期签到速度排列的工业啤酒和精酿啤酒列表）。无参数。

酿酒厂

get_brewery_info

获取酿酒厂的详细信息、啤酒列表和近期签到动态。

参数	类型	必填	描述
brewery_id	integer	是	Untappd 酿酒厂 ID
compact	boolean	否	如果为 true，则仅返回酿酒厂信息

get_brewery_checkins

获取酿酒厂最近的公开签到动态——其所有啤酒在全球范围内的签到。

参数	类型	必填	描述
brewery_id	integer	是	Untappd 酿酒厂 ID
limit	integer	否	每页结果数（最多 50，默认值为 25）
max_id	integer	否	返回签到 ID 早于此 ID 的结果
min_id	integer	否	仅返回签到 ID 晚于此 ID 的结果

用户

get_user_info

获取 Untappd 用户的个人资料和统计数据。

参数	类型	必填	描述
username	string	是	Untappd 用户名
compact	boolean	否	如果为 true，则仅返回用户信息（不包含签到、媒体和近期酿造记录）

get_user_activity

获取用户最近的签到动态。

参数	类型	必填	描述
username	string	是	Untappd 用户名
limit	integer	否	结果数量（最多 25，默认值为 25）
max_id	integer	否	返回签到 ID 早于此 ID 的结果
min_id	integer	否	仅返回签到 ID 晚于此 ID 的结果

get_user_distinct_beers

获取用户签到过的不同啤酒，并支持灵活的排序方式。使用 sort=checkin 和 limit=1，即可通过单次调用获取“签到次数最多的啤酒”。

参数	类型	必填	描述
username	string	是	Untappd 用户名
offset	integer	否	分页偏移量
limit	integer	否	每页结果数（最多 50，默认值为 25）
sort	string	否	date（默认值）、checkin、highest_rated、lowest_rated、highest_rated_you、lowest_rated_you

get_user_wishlist

获取用户心愿单中的啤酒。

参数	类型	必填	描述
username	string	是	Untappd 用户名
offset	integer	否	分页偏移量
limit	integer	否	每页结果数（最多 50，默认 25）
sort	string	否	date（默认）、checkin、highest_rated、lowest_rated

get_user_badges

获取用户获得的徽章（每页 50 个，按时间从新到旧排列）。

参数	类型	必填	描述
username	string	是	Untappd 用户名
offset	integer	否	分页偏移量（每页 50 个）

get_user_friends

获取用户的好友列表（仅限公开账户）。

参数	类型	必填	描述
username	string	是	Untappd 用户名
offset	integer	否	分页偏移量
limit	integer	否	每页结果数（最多 50，默认 25）

动态信息流

get_global_feed

获取全球公开签到动态（The Pub）。相对于返回的数据，速率限制消耗较高——建议使用 min_id 轮询，仅获取新的签到。注意： 标准 API 密钥通常无权访问 /thepub——除非密钥具有更高权限，否则 Untappd 会返回 "You are not authorized to call this method from this key"（get_local_feed 不受此限制）。

参数	类型	必填	描述
limit	integer	否	每页结果数（最多 50，默认 25）
max_id	integer	否	返回 ID 早于此签到 ID 的结果
min_id	integer	否	仅返回 ID 晚于此 ID 的签到

get_local_feed

获取指定地理位置附近的公开签到动态。

参数	类型	必填	描述
lat	number	是	纬度
lng	number	是	经度
radius	integer	否	半径，单位为 英里（默认 25，最大 50）
limit	integer	否	每页结果数（最多 50，默认 25）
max_id	integer	否	返回 ID 早于此签到 ID 的结果
min_id	integer	否	仅返回 ID 晚于此 ID 的签到

get_friend_feed 🔑 token

获取已认证用户的好友签到动态。

参数	类型	必填	描述
limit	integer	否	每页结果数（最多 50，默认 25）
max_id	integer	否	返回 ID 早于此签到 ID 的结果
min_id	integer	否	仅返回 ID 晚于此 ID 的签到

签到

get_checkin_info

获取特定签到的详细信息，包括获得的徽章、碰杯和评论。

参数	类型	必填	描述
checkin_id	integer	是	Untappd 签到 ID

复合 / 聚合

这些工具会发起多次 API 调用（每扫描一页调用 1 次——每页 50 款啤酒 / 个徽章，或 25 条签到）。它们会在开始前检查剩余速率限制，并在额度不足时提前停止——在响应中将 truncated: true。

get_user_stats_at_venue

通过扫描用户最近的签到动态，获取其在特定场所的签到统计数据——到访次数、最近到访时间、平均评分和最常签到的啤酒。Untappd API 没有场所历史记录端点，因此统计数据仅涵盖扫描的时间范围（max_pages × 25 条签到），而非所有时间。

参数	类型	必填	描述
venue_id	integer	是	Untappd 场所 ID
username	string	否	Untappd 用户名（默认使用 UNTAPPD_USERNAME）
max_pages	integer	否	要扫描的动态页数上限，每页 25 条签到（默认 5 页，即 125 条签到）

search_venue_then_get_user_stats

按名称搜索场所，然后获取用户在最匹配结果中的签到统计。

参数	类型	必填	描述
q	string	是	场所搜索查询
username	string	否	Untappd 用户名（默认使用 UNTAPPD_USERNAME）
lat	number	否	用于基于位置搜索的纬度
lng	number	否	用于基于位置搜索的经度
max_pages	integer	否	要扫描的动态页数上限，每页 25 条签到（默认值 5 = 125 条签到）

get_user_beer_stats

将用户不同啤酒的历史记录汇总为风格、啤酒厂和评分细分数据——热门风格、热门啤酒厂、个人与全球平均评分、评分最高的啤酒以及签到次数最多的啤酒。

参数	类型	必填	描述
username	string	是	Untappd 用户名
max_pages	integer	否	要扫描的页数上限，每页 50 款啤酒（默认值 10 = 500 款啤酒）

get_user_badge_summary

获取用户的所有徽章（翻页直至完成），并提供结构化摘要。

参数	类型	必填	描述
username	string	是	Untappd 用户名
max_pages	integer	否	要扫描的页数上限，每页 50 枚徽章（默认值 10 = 500 枚徽章）

速率限制

Untappd API 每个 API 密钥每小时允许 100 次调用（通过访问令牌进行身份验证时，按访问令牌计算）。每个工具响应都会包含当前速率限制状态：

{
  "rateLimit": {
    "limit": 100,
    "remaining": 97
  }
}

组合工具会在开始翻页前调用 assertRateLimitSufficient，并在预算耗尽前提前停止，返回 truncated: true。如果超出限制，Untappd API 会返回 429 错误，显示为：Rate limit exceeded. Limit: 100, Remaining: 0. Resets hourly.

身份验证

模式	环境变量	可用功能
公共	UNTAPPD_CLIENT_ID + UNTAPPD_CLIENT_SECRET	所有公共工具
已验证身份	+ UNTAPPD_ACCESS_TOKEN（+ 可选的 UNTAPPD_USERNAME）	get_friend_feed、用户级速率限制、更丰富的 /user 数据

配置访问令牌后（通过环境变量或已保存的令牌文件），服务会优先使用该令牌进行所有调用——速率限制将按用户计算，/user 端点也会返回更丰富的数据。UNTAPPD_USERNAME 会为已验证身份的用户工具提供默认用户名。

如果既未配置客户端 ID/密钥，也未配置访问令牌，服务会在启动时退出。

交互式身份验证

无需手动获取访问令牌——服务可以代你运行 Untappd 的 OAuth 流程。

**一次性前置要求：**在 Untappd 应用设置中的 untappd.com/api 页面，将 Callback URL 设置为以下确切值：

http://localhost:8737/callback

（或者设置为 UNTAPPD_REDIRECT_URL 的值；该值必须是 localhost http URL，且两者必须完全一致，否则 Untappd 会拒绝此流程。）

**在聊天中：**让你的 Agent 运行 authenticate_untappd 工具。浏览器会打开 Untappd 的授权页面；批准后，令牌就会保存，🔑 工具可立即使用——无需重启。

在终端中：

npx untappd-mcp-server auth            # run the interactive flow
npx untappd-mcp-server auth --status   # show current auth status
npx untappd-mcp-server auth --clear    # delete the saved token

（在仓库中运行：npm run auth。）

**存储与优先级：**令牌会保存到 ~/.untappd-mcp-server/token.json（可通过 UNTAPPD_TOKEN_PATH 覆盖）。如果设置了 UNTAPPD_ACCESS_TOKEN，它始终优先于文件中的令牌。Untappd 令牌不会过期。

**安全提示：**令牌以明文存储；在 macOS/Linux 上，文件权限为 0600；在 Windows 上，保护依赖于用户配置文件的 ACL。可随时通过 auth --clear 删除令牌。工具输出只会包含令牌的掩码形式。

开发

npm install
npm run build
npm test          # unit tests (mocked API — no rate limit cost)
npm run smoke     # live smoke test against the real API (~25 calls, ~26 with a token)

冒烟测试会使用你的 UNTAPPD_* 环境变量；如果未设置访问令牌，则会跳过需要身份验证的工具；如果剩余速率限制低于 5，则会中止。使用 npm run smoke -- --only=tool_name 可将测试限制为单个工具。

使用 MCP Inspector 进行测试

npx @modelcontextprotocol/inspector node dist/index.js

已知限制

• 没有酒头列表数据 — 实际酒头列表需要订阅 Untappd for Business。场所签到动态可作为实时替代数据。
• 没有场所活动 — Untappd 的公共 API 没有活动端点，而原本可用于弥补这一缺口的 Eventbrite 搜索 API 已停止服务；此功能推迟至 v3。
• 没有场所历史记录端点 — v4 API 没有按用户查询场所历史记录的端点；get_user_stats_at_venue 会改为扫描最近的签到动态，因此其统计数据仅涵盖一个时间窗口（max_pages × 25 条签到），而非全部历史数据。
• 速率限制：每小时 100 次 — 尽量减少冗余调用；每个响应都会显示 rateLimit.remaining。
• 动态数量上限 — 工具接受最高为 50 的 limit，但部分动态会受到 API 服务器端 25 条的上限限制。
• 全局动态需要更高权限的密钥 — 标准 API 密钥无权访问 /thepub（get_global_feed）；本地动态适用于任何密钥。
• Foursquare 查询需要 v2 ID — 即 MD5 哈希格式；Foursquare v3 数字 ID 不可用。
• 需要场所 ID — 请先使用 venue_search 将场所名称解析为 ID。
• 仅限公开签到 — 无法查看私密用户账户。
• 只读 — 写入操作（签到、举杯、评论、愿望清单管理）推迟至 v3。
• MCP 客户端超时 — 某些 MCP 客户端会将工具调用时长限制在 authenticate_untappd 默认的 180s 以下；如果客户端先超时，请传入更小的 timeout_seconds，或者改为在终端中使用 npx untappd-mcp-server auth。

许可证

MIT