用途
yellowpages-mcp 是一个托管的 Model Context Protocol (MCP) 服务器，让 AI 客户端（如 Claude、Cursor、Windsurf）能够以编程方式访问 Yellow Pages 的公开本地商户信息。它面向需要生成销售线索、商户调研、竞品或覆盖度分析等场景，把原本需要浏览器或爬虫库完成的工作，转化为代理可直接推理的 JSON 数据。
主要能力
服务器只暴露两个只读工具：
-
hasdata_yellowpages_search_getSearchResults：按关键词和地点返回一页商户，每页 30 条。返回searchInformation（回显查询与totalResults）、organicResults数组，以及pagination（含currentPage、totalPages、perPage、nextPageUrl、otherPageUrls）。结果字段几乎都是可选的：样例中 30 条结果里title、phone、url、categories、country、position全部存在，address出现在 22 条，rating和reviews出现在 11 条，contactUs出现在 5 条。 -
hasdata_yellowpages_place_getPlaceDetails：按 Yellow Pages URL 返回单条完整列表，包含四个块：overview（名称、位置、电话、营业时间、徽章、网站，并附加paymentAccepted和breadcrumbs分类路径数组）、ratings（星级评分）、details（商家撰写的长文，其中generalInfo、servicesProducts、brands、paymentMethod、categories均为逗号连接字符串，而非数组）、images（照片 URL 数组）。details块是信息增值的主要来源。
此外服务器提供 2 个资源（resources），对应两个接受固定值列表的参数，URI 格式为 hasdata://yellowpages/<parameter>，读取不消耗积分，且无需 API key 即可读取。
使用方式
需要一个 MCP 客户端和一个 HasData API key（在仪表板创建，免费且无需信用卡）。这是远程服务器，最简单的方式是使用 URL 加 x-api-key 请求头，无需运行容器。仅支持 stdio 的客户端可通过薄启动器访问，启动器已发布为 npm 上的 @hasdata/yellowpages-mcp 和 PyPI 上的 hasdata-yellowpages-mcp。
服务器 URL 对所有客户端相同。支持 OAuth 的客户端可将同一 URL 作为连接器添加并登录，无需在配置文件中放置密钥：设置 → 连接器 → 添加自定义连接器，粘贴 https://mcp.hasdata.com/mcp?apis=yellowpages 并登录。
Claude Desktop 只加载本地（stdio）服务器，因此通过 stdio 启动器访问远程服务器。@hasdata/yellowpages-mcp 包即该启动器，从环境变量读取密钥。在 claude_desktop_config.json 中添加配置。若使用 Python，可将启动器换成 PyPI 包，用 uvx 运行而无需手动安装。Cursor 使用 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（单项目）；Windsurf 使用 ~/.codeium/windsurf/mcp_config.json，且字段名为 serverUrl 而非 url；VS Code 使用工作区中的 .vscode/mcp.json。
示例提示词：查找 Austin, TX 的水管工并按评分相对评论数排序；列出该邮编下所有带电话和营业时间的 HVAC 承包商；读取某条 Yellow Pages 列表并说明其服务的品牌。命名了细分行业和城市的提示词会调用搜索工具；读取服务、品牌和支付方式需要针对每个商家进行第二次调用。
适用场景
- 生成潜在客户列表（搜索工具一次调用即可获得名称、电话、地址、类别、营业时间、徽章，以及 Yellow Pages 展示时的评分和评论数）
- 商户信息丰富化（place 工具补充描述、服务列表、品牌和照片，每个商家消耗一次调用）
- 按平均评分等服务端排序（使用
sort: averageRating参数） - 覆盖度统计、评分比较、代理商机调研
限制与注意事项
- 计费：每个 Yellow Pages 工具每次成功调用消耗 10 积分。响应大小不影响价格。非 200 响应不计费，但成功返回空结果的调用仍计费。
- 免费额度：每月 1,000 积分（无需信用卡），约等于 100 次调用，随计费周期续期。
- 付费计划：起步 $59/月 200,000 积分（20,000 次调用），单价随量下降。当前数字见定价页。
- 并发限制：免费 1 个并发请求，Startup 5，Basic 15，Growth 层级 50 至 500。无人值守场景需对 429 做退避重试。
- 数据可靠性：除名称、电话、URL 和类别外，几乎所有字段都是可选的，应防御性读取。
- 评论数：应从搜索结果读取，place 工具的
ratings.reviews在所有检查的列表中都等于ratings.rating，不含计数。 ratings可能完全缺失，而非空对象。details字段为逗号连接字符串，categories在两个工具间类型不同（搜索结果为数组，details 中为字符串）。website有时指向 Yellow Pages 自身跟踪 URL，存储或使用前应检查主机。- 经营年限是徽章（
badges）而非字段，需阅读文字而非第一个数字。 - 街道地址不保证存在，需从
city、region、zipcode等字段构建。 openState是调用时刻的快照，workingHours才是持久字段。- 分页按 URL 进行，成本随页数增长，应先收窄关键词。
- 覆盖范围：美国 yellowpages.com 和加拿大 yellowpages.ca，通过
domain参数切换。 - 合规：列表为商业记录，但使用收集到的电话号码进行呼叫和短信受 TCPA 及 FTC 电话营销规则等单独监管；个体经营者的列表可能含个人姓名和手机号，构成个人数据。
- 无官方 Yellow Pages MCP 服务器或公开 API，本服务器由 HasData 维护，与 Yellow Pages 品牌无关联、背书或赞助关系。
测试与许可
仓库中的测试断言工具契约（参数、名称、必需参数、描述、sort 选项、key 是否被接受），其中一项测试会真实调用工具并消耗 10 积分；契约套件每周按计划运行。项目采用 MIT 许可。
