用途
yelp-mcp 是一个托管式 Model Context Protocol（MCP）服务器，让 Claude、Cursor、Windsurf 及其他 MCP 客户端能够以结构化 JSON 的形式读取 Yelp 的公开信息。它提供三个只读工具：按关键词和地点搜索商家、读取单个商家的完整详情、以及翻页获取商家的完整评论流。无需 Yelp Fusion 密钥，也无需自行托管任何容器。
它读取的是未登录访客可见的公开 Yelp 页面，覆盖 41 个区域域名。
主要能力
三个工具每次成功调用消耗 10 积分，均接受 domain 参数用于切换国家/地区（41 个可选值，从 www.yelp.com 到欧洲、亚洲、拉丁美洲站点，包括语言变体如 fr.yelp.ca、zh.yelp.com.hk）。
搜索（hasdata_yelp_search_getSearchResults）：返回指定地点中某关键词的一页商家。响应包含 searchInformation（回显的 keyword、location、totalResults）、ads 付费广告数组、organicResults 自然结果数组，以及分页信息（currentPage、perPage、totalPages、nextPageUrl、otherPagesUrls）。两个结果数组结构不同：自然结果带有 position 和 streetAddress，广告则没有这两项，但额外有 phone 和 highlights 徽章数组。合并两个数组时若不区分来源，会把付费展示误当成排名。
商家详情（hasdata_yelp_place_getPlaceDetails）：返回一个 placeResult 对象，包含 name、url、address、neighborhoods、country、phone、website、price、categories、rating、reviews、isClaimed、isClaimable，以及 operationHours（一周营业时间加 today）、features 数组、menu 对象（含 popularDishes）、faqs 数组、reviewHighlights 数组、images 数组和 businessMap（静态地图图片 URL）。features 是设施区块，每项带 title 和 isActive 标志，false 表示 Yelp 明确声明该设施不存在，而非未知；过滤时丢弃 false 条目与丢弃缺失条目含义不同。
评论流（hasdata_yelp_reviews_getPlaceReviews）：返回单个商家的完整评论文本，支持排序、过滤和分页。响应包含 searchInformation（商家名称、别名、URL、totalResults、rating、reviewCountsByRating 数组、reviewCountsByLanguage 细分）、pagination 对象和 reviews 数组。每条评论包含 position、id、link、user 对象、comment 对象（text 及检测到的语言）、date、rating，以及可选的 photos、videos、reactions。user 对象报告 name、userId、address、终身评论数、好友数、照片数，以及 Yelp Elite 成员的 eliteYear。作者后来重写的评论还会携带 previousReviews，其中保存了旧版本的文本、评分和日期——当问题涉及评分是否变动时，该字段是关键，因为仅看当前评论无法回答。
服务器还提供一个 prompt（预置工作流），以及 2 个资源，每个对应一个取值固定的参数，URI 格式为 hasdata://yelp/<parameter>。读取资源不消耗积分，且无需 API 密钥。
使用方式
需要 MCP 客户端和 HasData API 密钥（在控制面板免费创建，无需信用卡；免费层按 10 积分/次计算每月约支持 100 次调用）。这是远程服务器，最简路径是 URL 加 x-api-key 头，无需运行容器。仅支持 stdio 的客户端可通过轻量启动器访问，启动器已发布为 npm 包 @hasdata/yelp-mcp 和 PyPI 包 hasdata-yelp-mcp。
服务器 URL 对所有客户端相同：https://mcp.hasdata.com/mcp?apis=yelp。
支持 OAuth 的客户端可将该 URL 添加为连接器并直接登录，无需在配置文件中放入密钥。在设置 → 连接器 → 添加自定义连接器，粘贴上述 URL 并登录即可。
对于配置文件方式，Claude Desktop 仅加载本地（stdio）服务器，因此通过 stdio 启动器到达远程服务器。@hasdata/yelp-mcp 包即该启动器，从环境变量读取密钥。将其加入 claude_desktop_config.json。若使用 Python 而非 Node，可换用 PyPI 包，由 uvx 运行而无需手动安装。
Cursor：将配置放入 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）。
Windsurf：配置文件为 ~/.codeium/windsurf/mcp_config.json，字段名为 serverUrl 而非 url。
VS Code：使用工作区内的 .vscode/mcp.json。
适用场景
典型提示词示例：
- 在 Austin, TX 寻找咖啡烘焙商，并按评分与评论数排名。
- 获取 Yelp 商家 desnudo-coffee-austin 的营业时间、电话和网站。
- 读该商家所有一星和二星评论，按主题归类抱怨。
- Yelp 列出该店哪些热门菜品，评论者怎么说？
- 比较同一街区三家竞品的评分分布。
- 展示 Yelp 不推荐的评论，并与推荐评论对比差异。
提示词若直接点名商家而非 Yelp ID，需要两次调用：一次搜索解析 ID，一次详情或评论读取。搜索工具同时返回 placeId 和 placeAlias，两者均可作为 place 工具的 placeId 参数。
限制与注意事项
- 搜索无匹配时返回成功结果但 organicResults 为空数组，requestMetadata.status 仍为 ok。迭代前应先检查数组长度。
- snippet 是带标记的文本，Yelp 用 [[HIGHLIGHT]] 和 [[ENDHIGHLIGHT]] 包裹匹配词，需在索引、嵌入或展示前剥离。
- 分类 URL 是 HTML 转义的，categories 条目中的 url 含
&而非裸 &，需先反转义。 - rating 和 query 在评论工具上不能组合：Yelp 在运行全文查询时忽略星级过滤，需要两者时须自行过滤结果。
- start 和 nextPageToken 是两种分页方式，不能混用。令牌同时携带偏移量和页大小，单独重发即可继续；start 需要 num 在多次调用间保持不变。
- notRecommended 返回被 Yelp 从主列表过滤掉的评论，每次 10 条（而非 49 条），且不带 photos、videos、reactions。
- 商家可能未被认领，未认领页面信息稀疏：isClaimed 为 false 通常意味着没有网站、营业时间和设施，因为无人填写。应将缺失字段与此区分。
- 携带数据的响应也带有 requestMetadata.id，便于在支持时引用。
计费与并发
每次成功调用 10 积分，响应大小不影响价格，因此 49 条评论页与 5 条评论页同价，读取评论流时选最大页最划算。
免费层每月 1000 积分且无需信用卡，即基础费率下 100 次调用，随账单周期重置，低流量代理可长期使用免费层。
付费计划起步 $59/月获得 200,000 积分（即 20,000 次调用），单价随量下降，从入门计划的每千次 $2.95 降至 Basic 的 $1.19、Growth 各档的 $0.83。最新数字见定价页。计划同时决定并发：免费层 1 请求/次，Startup 5，Basic 15，Growth 各档 50 至 500。无人值守场景遇 429 应退避重试，因为面向多个商家展开的代理会先触及上限。非 200 响应不计费，但成功调用但无结果仍计费。
与其他方案比较
Yelp 官方 Fusion API 是获取该数据的官方途径，但性质不同。决定取舍的是评论文本：Fusion 每商家返回三条摘录，适合店面展示问题，无法回答关于情感、抱怨或评分变动的分析问题。若需要三条摘录和官方合约，Fusion 更合适。
Yelp 未发布官方 MCP 服务器；本服务器由 HasData 维护，仅读取公开 Yelp 页面。
合规与个人数据
评论工具返回个人数据：评论携带作者显示名、头像、所述地点、用户 ID 及个人主页链接，评论者多为个人而非企业，这使响应在 GDPR 和 CCPA 下比商家列表更敏感。存储前应决定实际需要什么，不超目的所需时长保留，并核实自身义务。聚合分析通常完全不需要作者字段。
HasData 与 Yelp 无关联、未获其背书或赞助，Yelp 是其各自所有者的商标。工具仅使用公开数据，用户需自行确保使用方式符合 Yelp 条款及适用法律。
其他
启动器是到远程服务器的轻量 stdio 桥，无需构建。test/ 中的测试断言工具契约，检查 ?apis=yelp 返回预期工具数、名称未变、每个工具仍声明必需参数并带描述、所用密钥确实被接受；最后一项会真实调用工具并消耗 10 积分。契约套件还按周计划运行，因为上游工具列表可能在本仓库未变动时改变。使用 MIT 许可证，详见 LICENSE。
