HasData Yelp

Yelp MCP 服务

一个托管的模型上下文协议（MCP）服务，为 Claude、Cursor、Windsurf 以及其他任何 MCP 客户端提供三个只读 Yelp 工具。按关键词和地点搜索商家、完整读取某家商家的信息，以及分页浏览其全部评论，所有内容均以结构化 JSON 返回，无需 Yelp Fusion 密钥，也无需自行托管。

它读取已退出登录的访客可见的 Yelp 公开页面，支持全部 41 个区域域名。

每月提供 1,000 个免费额度，无需信用卡，按每次调用 10 个额度计算，可调用 Yelp 100 次。

https://mcp.hasdata.com/mcp?apis=yelp

• 提示词和资源

目录

• 所需条件
• 快速开始
• 示例提示词
• 工具
• 错误和失败处理
• 定价、免费套餐和限制
• 工具选择
• 对比
• 常见问题
• HasData 链接
• 开发
• 贡献
• 许可证

所需条件

一个 MCP 客户端，以及从控制面板获取的 HasData API 密钥。注册免费，无需信用卡；免费套餐按每次调用 10 个额度计算，每月约可调用 100 次。这是一个远程服务，因此最简单的接入方式是使用 URL 和 x-api-key 标头，无需运行容器。仅支持 stdio 的客户端可通过轻量启动器连接该服务。启动器已发布至 npm（@hasdata/yelp-mcp）和 PyPI（hasdata-yelp-mcp），下文将对此进行介绍。

快速开始

所有客户端使用相同的服务器 URL。我们会在 Claude Code 和 Claude Desktop 中手动运行。其他代码块遵循各客户端针对远程服务记录的文档格式。

支持 OAuth 的客户端可以将相同的 URL 添加为连接器，然后登录，无需在配置文件中填写密钥。

claude mcp add --transport http yelp "https://mcp.hasdata.com/mcp?apis=yelp" \
  --header "x-api-key: HASDATA_API_KEY"

{
  "mcpServers": {
    "yelp": {
      "command": "npx",
      "args": ["-y", "@hasdata/yelp-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "yelp": {
      "command": "uvx",
      "args": ["hasdata-yelp-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "yelp": {
      "url": "https://mcp.hasdata.com/mcp?apis=yelp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "yelp": {
      "serverUrl": "https://mcp.hasdata.com/mcp?apis=yelp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "servers": {
    "yelp": {
      "type": "http",
      "url": "https://mcp.hasdata.com/mcp?apis=yelp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

示例提示词

每个提示词都会调用一个工具；如果第二个工具需要第一个工具返回的标识符，则会依次调用两个工具。

• 查找德克萨斯州奥斯汀的咖啡烘焙店，并根据评分与评论数对它们进行排名。
• 获取 Yelp 商家 desnudo-coffee-austin 的营业时间、电话和网站。
• 阅读这家商家的所有一星和二星评论，并按主题归纳投诉。
• Yelp 将哪些菜品列为这家店的热门菜品？评论者对这些菜品有什么评价？
• 比较同一社区内这三家竞争对手的评分分布。
• 显示 Yelp 不推荐的这家商家的评论，并说明它们与推荐评论有何不同。

如果提示词中提到的是商家名称而非 Yelp ID，则需要调用两次：先搜索以解析 ID，再查询地点或评论。搜索工具会同时返回 placeId 和 placeAlias，二者都可以作为地点工具的 placeId 参数。

工具

共有三个工具，每次成功调用消耗 10 个 credits。每个工具都接受 domain 参数以切换国家／地区，可选值共 41 个，范围从 www.yelp.com 到欧洲、亚洲和拉丁美洲的网站，包括 fr.yelp.ca 和 zh.yelp.com.hk 等特定语言版本。

获取 Yelp 搜索结果

hasdata_yelp_search_getSearchResults

搜索指定地点中符合关键词的一页商家。

返回的 searchInformation 包含回显的 keyword、location 和 totalResults；ads 数组包含付费展示结果，organicResults 数组包含自然搜索结果，pagination 则包含 currentPage、perPage、totalPages、nextPageUrl 和 otherPagesUrls。

这两个结果数组的结构并不相同。自然搜索结果包含 position 和 streetAddress，而广告结果不包含这两个字段，并新增了 phone 和 highlights 数组，其中列出 Yelp 向广告商展示的徽章。如果不先确认商家来自哪个数组就将两者合并，付费展示结果就会被误认为排名结果。

{
  "position": 2,
  "placeId": "oiJ7QuhhpsEpe9zFTZF0bA",
  "placeAlias": "desnudo-coffee-austin",
  "url": "https://www.yelp.com/biz/desnudo-coffee-austin",
  "title": "Desnudo Coffee",
  "streetAddress": "2505 Webberville Rd, Austin",
  "price": "$$",
  "categories": [{ "title": "Coffee Roasteries", "url": "https://www.yelp.com/search?find_desc=Coffee+Roasteries&find_loc=Austin%2C+TX" }],
  "snippet": "My favorite coffee shop to go to ever! Everyone must go. [[HIGHLIGHT]]Great coffee[[ENDHIGHLIGHT]], great vibes,great customer...",
  "rating": 4.7,
  "reviews": 347,
  "thumbnail": "https://s3-media0.fl.yelpcdn.com/bphoto/0nE_IcbRiyxrw3kk2z6owg/ls.jpg",
  "allImagesUrl": "https://www.yelp.com/biz_photos/oiJ7QuhhpsEpe9zFTZF0bA"
}

获取 Yelp 商家详情

hasdata_yelp_place_getPlaceDetails

获取单个商家的完整信息。

返回一个 placeResult 对象，包含 name、url、address、neighborhoods、country、phone、website、price、categories、rating、reviews、isClaimed 和 isClaimable；一个 operationHours 对象，其中包含一周的 hours 和当天的 today；一个 features 数组；一个包含 popularDishes 的 menu 对象；一个 faqs 数组，列出 Yelp 用户提问并回答的问题；一个 reviewHighlights 数组，列出 Yelp 固定显示在页面顶部的短语；一个 images 数组；以及 businessMap，即静态地图图片 URL。

features 是设施信息块，每个条目都包含 title 和 isActive 标记，因此值为 false 的条目表示 Yelp 确认该设施不存在，而不是未知。筛选时这一区别很重要，因为丢弃值为 false 的条目和丢弃缺失的条目，并不是同一个查询。

{
  "name": "Desnudo Coffee",
  "url": "https://www.yelp.com/biz/desnudo-coffee-austin",
  "address": "2505 Webberville Rd Austin, TX 78702",
  "neighborhoods": "East Austin",
  "country": "US",
  "phone": "(424) 400-1857",
  "website": "http://www.desnudocoffee.com",
  "price": "$$",
  "categories": ["Coffee Roasteries"],
  "rating": 4.7,
  "reviews": 347,
  "isClaimed": true,
  "isClaimable": false,
  "operationHours": { "hours": [{ "day": "Mon", "hours": ["7:00 AM - 2:00 PM"] }] },
  "features": [
    { "title": "Offers delivery", "isActive": true },
    { "title": "ADA-compliant restroom", "isActive": false }
  ],
  "menu": {
    "section": "Popular Drinks",
    "popularDishes": [{ "name": "Brown Sugar Miso Latte", "rating": 4.7, "reviews": 113, "photos": 71 }]
  }
}

获取 Yelp 商家评论

hasdata_yelp_reviews_getPlaceReviews

获取某家商家的完整评论动态，可排序、筛选和分页。

返回的 searchInformation 包含商家名称、别名、URL、totalResults、rating、reviewCountsByRating 数组和 reviewCountsByLanguage 分类统计，以及一个 pagination 对象和一个 reviews 数组。

每条评论都包含 position、id、link、一个 user 对象、一个包含 text 和检测到的 language 的 comment 对象、date、rating，以及评论者附加的 photos、videos 和 reactions（如果有）。user 对象会提供 name、userId、address、累计 reviews 数量，以及 friends 和 photos 数量；如果是 Yelp Elite 成员，还会提供 eliteYear。

如果作者后来改写了评论，评论还会包含 previousReviews，其中保存了较早版本及其文本、评分和日期。如果问题是评分是否发生变化，就应读取此字段，因为仅凭当前评论无法回答。

{
  "position": 1,
  "id": "7zLIm3c2v2hRBVmgaKkR7w",
  "link": "https://www.yelp.com/biz/desnudo-coffee-austin?hrid=7zLIm3c2v2hRBVmgaKkR7w",
  "user": {
    "name": "Karson S.",
    "userId": "3LxSs_dQ37-LBRz07EDbyg",
    "address": "Austin, TX",
    "reviews": 374,
    "friends": 61,
    "photos": 875,
    "eliteYear": "26"
  },
  "comment": { "text": "Coming back to Desnudo to update my old review...", "language": "en" },
  "date": "2026-08-20T17:33:47-05:00",
  "rating": 5,
  "photos": [{ "link": "https://s3-media0.fl.yelpcdn.com/bphoto/YbjFKmRf7j0ejQQSaqtqVw/o.jpg", "caption": "Matcha latte", "width": 1126, "height": 2000 }],
  "reactions": [{ "type": "HELPFUL", "label": "Helpful", "count": 1 }],
  "previousReviews": [{ "id": "0WNI2IG7K1_Dg9zdXm03SA", "rating": 4, "comment": { "text": "..." } }]
}

提示词和资源

该服务提供一个提示词，这是一套现成的工作流，客户端可以直接提供给用户，而无需让用户自行编写工具调用。

此外，该服务还公开 2 个资源，每个资源对应一个可接受值为固定列表的参数。读取资源比因调用被拒而了解相关取值更省事，而且不会消耗额度。每个 URI 的格式为 hasdata://yelp/<parameter>。

这两个列表均无需 API 密钥即可获取，因此客户端可以在用户注册前读取它们。

错误和失败路径

应对这些情况做好准备，而不是假设一切都会顺利。

搜索没有匹配结果时，会成功返回一个空的 organicResults 数组，而不是报错。requestMetadata.status 仍为 ok。迭代前先检查数组长度。

snippet 是带标记的文本，不是干净文本。 Yelp 会用 [[HIGHLIGHT]] 和 [[ENDHIGHLIGHT]] 包裹匹配的词语，这些标记会原样返回。将片段编入索引、生成嵌入或显示之前，先去掉这些标记。

类别 URL 会经过 HTML 转义。 categories 条目中的 url 包含 &，而不是裸的和号，因为页面上就是这样呈现的。跟进链接前先对其进行反转义。

在 reviews 工具中，rating 和 query 不能同时使用。 Yelp 在运行自由文本查询时会忽略星级筛选，因此筛选后的搜索结果会包含各种评分的评论。如果两者都需要，请自行筛选结果。

start 和 nextPageToken 是两种不同的分页方式，不能混用。 两者选其一传入。令牌同时包含偏移量和页面大小，因此只需重新发送令牌即可继续获取内容；而使用 start 时，必须通过 num 保持不同调用间的页面大小不变。

非推荐内容流是另一种内容流，限制也不同。 设置 notRecommended 会返回 Yelp 从主列表中过滤掉的评论，每次返回 10 条，而不是 49 条，并且不附带照片、视频或互动信息。

商家可能尚未认领，未认领的页面信息也很少。 isClaimed 为 false 通常意味着没有网站、营业时间和设施信息，因为没人填写这些内容。将缺失字段视为抓取失败之前，先检查此标记。

包含数据的结果也会包含 requestMetadata.id，遇到问题时值得在支持请求中引用。

定价、免费套餐和限制

每次成功调用 Yelp 工具需 10 个额度。响应大小不影响价格，因此，返回 49 条评论的页面和返回 5 条评论的页面价格相同；读取内容流时，获取最大页面最划算。

免费套餐每月提供 1,000 个额度，无需绑定银行卡，按基础费率可调用 Yelp 100 次。额度会随计费周期续订，因此低调用量的 Agent 可以无限期使用免费套餐。

付费套餐起价为 每月 $59，提供 200,000 个额度，即 20,000 次调用。随着用量增加，单价会降低：入门套餐为 每 1,000 次调用 $2.95，Basic 为 $1.19，Growth 套餐各档为 $0.83。最新价格请查看定价页面。

套餐还决定并发限制。免费套餐允许同时发起 1 个请求，Startup 为 5 个，Basic 为 15 个，Growth 各档则为 50 到 500 个。对于无人值守的任务，遇到 429 时应使用退避策略重试，因为跨多个商家并行发起请求的 Agent 会比你更早触及上限。

非 200 响应的请求不会计费。成功调用但没有找到结果，仍算一次调用。

工具选择

从提示词提供的信息入手。关键词和地点交给搜索工具，Yelp ID 或别名直接交给地点工具，有关顾客评价的问题则交给评论工具。已有 ID 却还要花一次搜索调用来获取 ID，是最常见的浪费。

接着根据问题内容选择工具。地点工具可回答有关商家本身、营业时间、设施、价格档次和总体评分的问题。评论工具可回答有关顾客的问题，也是唯一能返回评论文本、作者和评分分布的工具。地点工具中的 reviewHighlights 部分是 Yelp 精选的示例，不能替代评论内容流。

读取内容流时，选择最大的页面。num 默认已经是最大值 49，除非你有意抽样，否则不必调整。

对比

Yelp 自己的 Fusion API 是获取这些数据的官方途径，但它是另一种工具。

决定性差异在于评论文本。Fusion 为每家商户返回三条摘录，这适用于店面页面上的展示需求，却无法满足对情感、投诉或评分变化进行分析的需求。如果你只需要三条摘录和官方协议，Fusion 会更合适。

常见问题

Yelp 有官方的 MCP 服务吗？

Yelp 没有发布官方服务。此服务由 HasData 维护，读取 Yelp 的公开页面。

什么是 Yelp MCP 服务？

MCP 服务会公开 AI 客户端可以调用的工具。此服务会将 Yelp 搜索结果、商户页面和评论信息流转换为 JSON，供 Agent 进行推理，无需在技术栈中使用浏览器或抓取库。

我需要 Yelp 账号或 Fusion 密钥吗？

不需要。唯一需要的凭据是你的 HasData 密钥。

支持哪些 Yelp 网站？

API 接受的全部 41 个域名都受支持，从 www.yelp.com 到欧洲、亚洲和拉丁美洲的网站。有些国家/地区有多个网站，按语言区分，例如 fr.yelp.ca 和 www.yelp.ca。传入 domain 即可切换。

我能获取某家商户的所有评论吗？

可以，通过分页获取。每次返回 49 条，pagination.hasNextPage 会告诉你何时停止。读取一家有 347 条评论的商户需要调用八次。

推荐评论和未推荐评论有什么区别？

Yelp 会运行软件，将部分评论从主信息流中隐藏。默认响应是推荐评论信息流，也就是访客看到的内容。设置 notRecommended 后会返回隐藏的评论；这类评论数量较少，每页 10 条，且不包含照片和互动内容。

为什么我的评分筛选返回了所有评分？

因为同时设置了 query。Yelp 执行文本搜索时会取消星级筛选，因此两者无法在服务端组合使用。

我可以将此服务与其他 HasData API 搭配使用吗？

可以。一个密钥即可访问所有服务，一个端点通过 apis 参数提供所有服务。将客户端指向 ?apis=yelp,google_maps，即可在同一个连接中获取两组工具；也可以指向 mcp.hasdata.com/mcp，查看完整目录。

HasData 与 Yelp 有关联吗？

没有。HasData 是独立服务，与 Yelp 无关联，也未获 Yelp 认可或赞助。Yelp 是其各自所有者的商标。这些工具仅使用公开数据，你有责任确保使用结果时遵守 Yelp 的条款以及适用于你的法律。

合规与个人数据

评论工具会返回个人数据。评论中包含作者的显示名称、个人资料照片、自述所在地、用户 ID 以及个人资料链接；评论者是个人，而非商户。因此，与商户列表不同，这些响应属于 GDPR 和 CCPA 的管辖范围。存储数据前，请先确定实际所需；保存时间不得超过用途所需，并核查你自身的义务。汇总分析通常完全不需要作者字段。

HasData 链接

• Yelp Scraper API，这些工具背后的 REST 端点
• API 文档
• MCP 服务文档
• 定价
• 控制面板

其他 HasData MCP 服务：Google Search、Google Maps、Google Trends、Google Flights、DuckDuckGo、YouTube、TikTok、Instagram、Amazon、Zillow、Airbnb、Booking.com、Indeed。

开发

启动器是通往远程服务的轻量级 stdio 桥接，因此无需构建。

npm install
HASDATA_API_KEY=your_key_here npm test

test/ 中的测试用于验证工具契约，也就是可能在此仓库未提交任何更改的情况下发生变动的部分。它们会检查 ?apis=yelp 是否返回预期的工具数量、名称是否均未更改、每个工具是否仍声明了必需参数并附带说明，以及当前使用的密钥是否确实有效。最后一项检查会实际调用一个工具，耗费 10 个点数；这是一次可能因正确原因而失败的金丝雀测试所需的代价。

契约测试套件还会按计划每周运行，因为上游工具列表可能在无人修改此仓库的情况下发生变化。

贡献

如果工具表、响应示例或文档记录的行为与实际情况不符，欢迎提交 issue。我们专门为此提供了模板。欢迎提交相关拉取请求，也欢迎针对启动器中的任何内容提交拉取请求。

许可证

MIT，详见 LICENSE。