Listings API

Listings API MCP

将任何支持 MCP 的 AI 助手连接到 Listings API，即可管理 50 多个目录、地图和搜索引擎中的商家信息、评论、帖子和本地分析数据。

网站 · API 文档 · MCP 页面 · Claude 目录 · 获取 API 密钥 · Apify actors

---

Listings API 是什么

本地搜索依赖商家数据。商店、诊所或特许经营门店都有名称、地址、电话号码、营业时间、类别和照片。在搜索引擎足够信任这些数据并据此排名之前，Google、Apple Maps、Bing、Facebook、Yelp、语音助手以及数十个较小的目录中都必须有完全一致的数据。手动维护这些数据，一旦地点超过几个，就难以为继。

Listings API 是一款用于完成这项工作的 REST API。你只需存储每个地点的信息一次，API 就会将其同步到 50 多个平台，跟踪每条商家信息的上线状态，查找并抑制重复项，获取这些商家信息收到的评论，支持回复评论，向已连接的个人资料发布帖子和优惠，并返回 Google、Facebook 和 Bing 提供的效果数据。代理机构、多地点品牌和特许经营体系会用它在一个地方管理数百或数千个地点的本地线上形象。

这个 MCP 服务是什么

Model Context Protocol 允许 AI 助手调用外部工具。此服务将 Listings API 作为一组 MCP 工具提供，因此 Claude、Cursor、Windsurf、Gemini CLI 或 Cline 等助手可以通过自然对话查询你的地点、查看评论、起草并发布回复、安排帖子和获取分析数据，使用的都是你自己的账户和数据。

这是一个远程服务。它运行在 https://listingsapi.com/mcp，并使用 Streamable HTTP。无需安装本地服务包或进行构建。将客户端指向该 URL，通过其 OAuth 浏览器流程登录；如果客户端要求提供标头，也可以使用现有的 API 密钥。

https://listingsapi.com/mcp

在各目录中查找

此服务也列在以下目录中，你可以从客户端已使用的目录安装：

目录	条目
Claude	claude.ai/directory/listings-api
官方 MCP Registry	com.listingsapi/mcp
Cursor	cursor.directory/plugins/listings-api
Glama	glama.ai/mcp/connectors/com.listingsapi/mcp
Smithery	smithery.ai/servers/support-hxau/listingsapi
MCP.so	mcp.so/servers/listings-api
mcpservers.org	mcpservers.org/servers/listings-api/listingsapi-mcp

此仓库中的 Agent 技能另行列出；请参阅 Agent 技能。

你可以用它做什么

连接后，助手可以处理你账号中的五个方面。

地点。 创建和更新地点资料、搜索地点并查看其详情。地点是其发布商列表所使用的主记录。

列表和引用。 查看当前有哪些发布商收录了某个地点，以及每条列表的状态；列出你的套餐涵盖的网站；获取网络检测到的某个地点或整个账号的重复列表；将列表标记为重复项以便将其抑制，或者在匹配错误时清除该标记。语音助手覆盖情况会单独报告。

评论。 查看评论、按 ID 获取特定评论、检查评论分析数据，并在已连接的发布商支持时发布回复。已发布的回复会显示在评论网站上。

帖子。 查看现有帖子，并向支持的已连接资料发布帖子。请查看当前工具合约，了解支持的发布商和负载。

分析。 查看任意地点的 Google、Facebook 和 Bing 表现数据：搜索浏览量、地图浏览量、路线请求、电话、网站点击量等，以及你询问的任意日期范围内的数据。

此外，还有一组已连接账号操作，可用于关联 Google 或 Facebook 账号，将其资料与地点匹配，并为尚无 Google 商家资料列表的地点新建列表。

MCP 工具不提供归档地点和删除帖子等破坏性操作。请使用 MCP 指南和服务器的文档工具，查看当前可用的操作。

示例请求

连接服务器后，你可以向助手提出以下类型的请求。

• “列出我们在 Texas 的所有地点，并告诉我哪些地点缺少电话号码。”
• “显示过去一周所有门店中评分低于三颗星的评论，并按地点分组。”
• “为 Austin 门店最新的 Google 评论起草一条回复，控制在 60 个词以内，然后发布。”
• “向 Northeast 地区的所有地点发布一条优惠帖子，内容为维修服务打八折，活动持续到本月底。”
• “比较我们排名前十的门店本月和上个月的路线请求与电话数量。”
• “我们有哪些地点仍没有 Google 商家资料列表？”

你需要准备什么

一个 ListingsAPI 账号。生产环境访问权限请参阅套餐和注册，或者查看下方的 Day Pass 是否可用。支持 OAuth 的客户端可让你直接登录，无需将 API 密钥复制到配置文件中。

使用 Day Pass 免费体验一天

注册前请查看实时可用情况；Day Pass 仅在有限时段内开放。当 open 为 true 时，你可以通过 Day Pass 注册 启用免费的 24 小时沙盒。它最多涵盖 2 个地点，并同步到 10 个 ListingsAPI 演示目录。它绝不会向真实发布平台写入数据。评论、帖子、社交媒体、分析、已连接的账户和 webhook 均不包含在内。

注册时需要提供姓名、电子邮箱和公司信息，并接受服务条款和隐私政策。你通过邮件中的链接或 6 位数代码激活通行证时，24 小时计时开始。请阅读 Day Pass 指南，了解当前限制和激活步骤。在 OAuth 客户端中，使用 Day Pass 邮箱选择 给我发送登录链接。对于 API 密钥客户端，请在本地使用相同的 API 标头前缀配置 Day Pass 密钥。安装插件或技能不会开始通行证计时。

密钥带有访问级别。具有 Read 访问权限的密钥可用于所有查询和报告。创建和更新地点、回复评论、发布帖子以及连接账户，都需要具有 Write 访问权限的密钥。

该服务支持两种身份验证方式：

方法	标头	适用情况
OAuth 2.0	由客户端管理	客户端支持浏览器登录和授权流程
API 密钥	Authorization: API <your-key>	客户端需要静态标头；仅在本地设置中输入密钥

OAuth 使用公共客户端、PKCE 和动态客户端注册。无需预先签发客户端密钥。除非任务需要写入操作，否则请从只读访问权限开始。OAuth 令牌适用于 MCP 端点；REST 集成使用 API 密钥。

设置

按照下方对应客户端的说明操作。仅在本地设置中替换 API 密钥占位符，并将凭据保留在共享仓库之外。

Claude Code

claude mcp add --transport http listingsapi https://listingsapi.com/mcp --header "Authorization: API <your-api-key>"

Claude Desktop

打开 claude.ai/directory/listings-api，然后点击 连接。Claude 会运行登录流程，随后即可在 Claude Desktop 和 Claude.ai 中使用此连接器。

如果要改用 URL 添加，请打开设置，然后依次选择连接器和添加自定义连接器，并将 https://listingsapi.com/mcp 设为 URL。服务器首次请求身份验证时，Claude Desktop 会提示你进行身份验证。

Cursor

从 Cursor Directory 安装，或将其添加到 ~/.cursor/mcp.json，或添加到项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "listingsapi": {
      "url": "https://listingsapi.com/mcp"
    }
  }
}

点击服务器条目上的 连接，在浏览器中完成 OAuth。此仓库的 Cursor 插件使用相同的配置。如果需要使用 API 密钥进行身份验证，请在本地设置中该条目内添加 "headers": { "Authorization": "API <your-api-key>" }。

Windsurf

从编辑器的 MCP 设置中打开 MCP 配置文件；旧版 Windsurf 使用的路径为 ~/.codeium/windsurf/mcp_config.json。不同版本的编辑器可能使用不同路径。对于支持 OAuth 的客户端，请添加：

{
  "mcpServers": {
    "listingsapi": {
      "serverUrl": "https://listingsapi.com/mcp"
    }
  }
}

按照浏览器中的身份验证提示完成操作。若要使用 API 密钥进行身份验证，请在本地设置中该条目内添加 "headers": { "Authorization": "API <your-api-key>" }。请参阅当前的 Cascade MCP 文档，了解适用于你的编辑器版本的说明。

Gemini CLI

将此仓库安装为扩展：

gemini extensions install https://github.com/listings-api/listingsapi-mcp

重启 Gemini CLI，然后运行 /mcp auth listingsapi 并完成浏览器登录。使用 /mcp 检查连接和发现的工具。此扩展启用了 OAuth，无需设置 API 密钥。

如果要使用 API 密钥而非扩展，请将以下条目添加到 ~/.gemini/settings.json 中现有的 mcpServers 对象：

{
  "mcpServers": {
    "listingsapi": {
      "httpUrl": "https://listingsapi.com/mcp",
      "headers": { "Authorization": "API ${LISTINGSAPI_API_KEY}" }
    }
  }
}

通过本地环境提供 LISTINGSAPI_API_KEY。每次只使用一种连接配置。有关身份验证和配置详情，请参阅 Gemini 的 MCP 文档。

Cline

打开 MCP Servers，然后选择 Remote Servers，添加 https://listingsapi.com/mcp，并选择 Streamable HTTP。如果你的 Cline 版本提供 Authenticate，请完成身份验证。手动设置时，请使用 "type": "streamableHttp"；省略 type 时，默认使用旧版 SSE。Cline 安装指南包含完整配置、API 密钥备用方案和只读验证流程。

VS Code with GitHub Copilot

添加到 .vscode/mcp.json：

{
  "servers": {
    "listingsapi": {
      "type": "http",
      "url": "https://listingsapi.com/mcp",
      "headers": { "Authorization": "API <your-api-key>" }
    }
  }
}

其他客户端

使用可流式 HTTP 传输，并采用上述端点和标头。该服务不需要 SSE。

速率限制

请求计入你的 Listings API 套餐，而非此服务。Launch 套餐每分钟允许 10 次请求，Growth 套餐每分钟允许 50 次，Enterprise 套餐的限制按账户协商确定。超出限制时，API 会返回 429，并附带 retry_after_seconds 值，告知你需要等待多久。每个错误响应还会附带 correlation_id，你可以提供给支持团队，以便他们查找确切的请求。详情请见 listingsapi.com/docs/rate-limits。

实用提示：如果让助手“检查每个地点”，它会很乐意为每个地点发送一次请求。使用 Launch 套餐时，这意味着每调用 10 次就要暂停一次，因此请缩小问题范围，或让助手分批处理。

开始之前值得了解的事项

已连接的个人资料优先。 回复 Google 或 Facebook 评论、发布帖子以及查看发布者分析数据，都需要先将相应的 Google 或 Facebook 个人资料连接到你的账户，并与地点匹配。如果分析调用返回空结果或回复失败，通常是个人资料未匹配所致。请先连接并匹配，然后再运行工作流。

创建商家信息是异步的。 创建 Google Business Profile 商家信息时，成功响应表示请求已被接受，并不代表商家信息已上线。Google 会按自己的时间安排进行验证和配置。请稍后检查商家信息状态，不要想当然地认为它已经上线。

写入操作会产生实际影响。 通过此服务发布的回复会公开显示在评论网站上。帖子会在已连接的个人资料上发布。请像在控制面板中操作一样谨慎对待写入操作。

地点描述有最低长度要求。 新地点的描述至少需要 200 个字符，这是创建调用首次失败最常见的原因。

故障排除

症状	可能原因	处理方法
每次调用都返回 401	密钥错误、已过期或粘贴时多带了空格	在控制面板的 API Keys 部分重新生成密钥，并更新标头
写入操作返回 403	密钥只有 Read 权限	创建具有 Write 权限的密钥
429	已达到套餐速率限制	等待 retry_after_seconds 指定的时间，或让助手分批处理
分析数据返回空结果	个人资料未连接或未与地点匹配	运行已连接账户相关操作，将其关联并匹配
回复已被接受但不可见	评论网站仍在处理中	等待几分钟，然后刷新评论

Agent 技能

使用 Skills CLI 从此仓库安装所需的工作流。技能提供操作说明；安装期间不会配置凭据、授予访问权限或运行客户工作流。

这五个工作流技能列在 skills.sh 上，面向 OpenClaw 的通用 listingsapi 技能则位于 ClawHub。

npx skills add listings-api/listingsapi-mcp

技能	功能
listingsapi-listing-audit	检查资料完整性、发布商状态、有效链接和可能重复的条目；生成按优先级排序的修复计划。
listingsapi-review-management	分类处理评价、起草回复，并仅发布或编辑已批准的回复。
listingsapi-multi-location-posting	在选定地点准备并发布已批准的 Google/Facebook 营销活动，然后核实结果。
listingsapi-performance-reporting	比较效果与声誉，并明确说明日期范围、覆盖范围和数据时效注意事项。
listingsapi-integration	将 REST/SDK 身份验证、地点设置、发布商连接和提交检查集成到新应用或现有应用中。
listingsapi	通用账户导航、连接前提条件和 Day Pass 指南。

若要直接选择某个技能：

npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration

集成技能保留原有名称。其规范源文件位于 skills/ 下，以便按标准方式发现；原始的 listingsapi-integration/ 路径和 ZIP 文件则作为兼容副本保留。编辑规范集成技能后，运行 python3 scripts/package-integration.py。只读工作流需要读取权限；发布公开回复、发布营销活动、编辑资料和连接发布商，都需要先批准具体操作并授予写入权限。Day Pass 仅适用于沙盒地点和演示条目。

有关验证和发布步骤，请参阅 技能发布说明。GitHub 上的可用性与 skills.sh 索引彼此独立：skills.sh 常见问题 介绍了如何通过真实的 CLI 安装遥测数据发现技能。

文档与支持

• 完整 API 参考：listingsapi.com/docs
• MCP 服务页面：listingsapi.com/mcp
• Python 和 Node 的 SDK：listingsapi.com/sdks
• 用于将 API 集成到自有代码中的 Agent 技能：listingsapi-integration
• 用于定时和无代码场景的 Apify actors：apify.com/listingsapi
• 支持：[email protected]

关于此存储库

此存储库包含 MCP 目录和客户端读取的连接清单，以及账户工作流和开发者集成技能。它不包含任何产品代码。Listings API 服务本身为闭源服务，运行于 listingsapi.com。

文件	读取方
server.json	官方 MCP Registry（地址为 registry.modelcontextprotocol.io）
gemini-extension.json	Gemini CLI，在将此存储库安装为扩展时
mcp.json 和 .cursor-plugin/plugin.json	Cursor，用于市场插件
llms-install.md	Cline，以便自行配置服务
logo.svg	此 README 和上述目录
logo-400.png	Cline Marketplace，该平台要求使用 400×400 PNG
skills/listingsapi/SKILL.md	对话式账户工作流技能，已为 ClawHub 和兼容的技能客户端准备就绪
skills/listingsapi-*/	可独立安装的工作流和开发者集成技能
listingsapi-integration/	集成技能的生成式兼容副本，保留其原始文件路径
listingsapi-integration.zip	将 skills/listingsapi-integration/ 目录打包，供接受技能上传的客户端使用

请参阅市场提交说明，了解软件包路径、提交前提条件和当前测试状态。尚未针对这些更改运行 Cursor 和 Cline 设置测试。

许可证

此存储库中的清单以 MIT License 发布。请参阅 LICENSE。Listings API 本身的使用受 Listings API 条款约束。

skills/listingsapi/ 中的对话式技能以 MIT-0 发布，以兼容 ClawHub。存储库根目录的 MIT 许可证和现有集成技能均未更改。