核心用法
untappd-mcp 是一套面向精酿啤酒社交平台 Untappd 的 MCP 工具集，通过逆向工程复现其 iPad 应用（v4）的私有 API 协议，实现读写双重能力。用户需配置账号凭证及通过抓包获取的移动应用客户端密钥，完成身份认证后即可调用。
功能架构
搜索与信息查询：支持啤酒（beer）、酒厂（brewery）、场馆（venue）的三级搜索与详情获取，可查看评分、风格、IBU、ABV 等完整酒款信息。
用户数据读取：覆盖个人资料、历史打卡（check-ins）、愿望清单（wishlist）、喝过的独特酒款、徽章成就、好友列表及好友动态流，支持分页遍历。
社交互动写入：在确认机制（confirm-gated）保护下，可发布新打卡（含评分 0-5 分、评论、场馆定位）、为好友打卡点赞（toast）及发表评论。所有写操作默认返回模拟预览，仅在显式确认后执行真实网络请求。
高性能缓存系统：针对 Untappd API 无法高效回答"某用户是否喝过某酒"的设计缺陷，内置 SQLite 镜像层。untappd_sync_user_beers 可完整同步用户历史酒单（对任意公开用户均可全量），untappd_sync_checkins 同步详细打卡记录（仅支持本人全量）。缓存支持断点续传、增量更新，查询工具包括单酒/批量查询、未喝过滤、多维度筛选等。
显著优点
- 功能完整性：罕见地实现了 Untappd 的写入能力，包括打卡、点赞、评论，填补了官方 API 仅限只读的空白
- 性能优化创新：自建缓存层解决 API 结构性缺陷，将"是否喝过"查询从潜在数百次分页请求降为零次
- 数据新鲜度透明：每次缓存查询返回完整性元数据，明确告知数据覆盖范围，避免误判
- 安全设计：写操作强制确认门控，防止误触发帖；支持健康检查验证配置
潜在缺点与局限性
- 合规风险高：需抓包获取
CLIENT_ID/CLIENT_SECRET，违反 Untappd 服务条款，账号存在封禁可能 - 凭证管理复杂：需同时保管用户名、密码及逆向获取的应用密钥，泄露后果严重
- 缓存同步成本：首次全量同步需大量 API 调用，受 Untappd 速率限制约束
- 写入功能受限：暂不支持照片附件、愿望清单增删
- 第三方数据局限：他人详细打卡历史仅能获取最近约 50 条，缓存标记
history_truncated
适合人群
- 精酿啤酒爱好者，希望深度分析个人饮酒历史或生成数据报告
- 内容创作者，需批量查询酒款信息或自动化社交互动
- 开发者研究移动 API 逆向工程与安全实践（教育目的）
常规风险
账号封禁风险显著：Untappd 明确禁止非官方客户端，逆向工程凭证可能随时失效。建议配置独立账号，避免主账号暴露。抓包过程若使用代理工具，存在中间人攻击隐患。缓存数据库含完整饮酒记录，本地文件需妥善保管权限。