将 AI 智能体连接到 listingsAPI MCP

将 Claude、ChatGPT、Cursor 或 Gemini 连接到托管的 MCP 服务器，让助手使用与您相同的工具读取您的地点、商家信息和评价，并对其执行操作。

Listings API 在 https://listingsapi.com/mcp 托管了一个 Model Context Protocol（MCP）服务器。您无需安装或运行任何程序。支持 MCP 的 AI 助手会连接到该 URL，发现每个 REST 端点对应的工具以及几个文档工具，并通过这些工具操作您的账户。本指南介绍如何连接各个主流客户端，然后验证连接。

1. 了解智能体可以使用哪些工具

服务器提供了 60 多个工具，其中约三分之二为只读工具。工具按 REST 资源命名，因此 locations_search、listings_premium、reviews_respond 和 posts_create_social 的功能与对应端点相同，参数和响应结构也相同。search_docs、get_doc 和 get_endpoint 这 3 个文档工具让助手可以查询页面或端点规范，无需猜测请求体结构。

工具类别	示例	所需权限
地点	`locations_all`, `locations_search`, `locations_create`, `locations_update`	查询需要 Read，创建和更新需要 Write
商家信息	`listings_premium`, `listings_duplicates`, `listings_mark_duplicate`	Read，标记重复商家信息需要 Write
已连接的账户	`connected_accounts_list`, `connected_accounts_listings`, `connected_accounts_connect_listing`	Read，连接和导入需要 Write
评价	`reviews_list`, `reviews_get`, `reviews_respond`, `reviews_analytics`	Read，回复需要 Write
帖子	`posts_social_post_view`, `posts_create_social`	Read，发布需要 Write
分析	`analytics_google`, `analytics_facebook`, `analytics_bing`	Read
账户	`whoami`, `get_usage`, `get_subscription`, `recent_errors`	Read
文档	`search_docs`, `get_doc`, `get_endpoint`, `list_endpoints`	无

删除帖子或归档地点等破坏性操作不作为工具提供。请使用 REST API 或 SDK 执行这些操作，这样助手就无法自行移除数据。

2. 选择客户端的登录方式

每个客户端都通过以下 2 种方式之一进行身份验证。这 2 种方式在服务器端最终都使用相同的 API 密钥机制，因此速率限制和用量报告完全一致。

方式	需要粘贴的内容	适用场景
API 密钥请求头	将 `Authorization: API <your key>` 作为静态请求头	您可以控制配置文件的 CLI 和编辑器
OAuth 2.0	无需粘贴任何内容。客户端会打开浏览器，您登录后批准 `read` 或 `read write`	Claude 和 ChatGPT 等托管助手，或不应持有原始密钥的任何人

OAuth 使用带 PKCE 的授权码流程和动态客户端注册，因此客户端无需预先签发的凭据。元数据位于 https://listingsapi.com/.well-known/oauth-authorization-server。作用域为 read 和 write；未请求任何作用域的客户端会获得 read。每次批准都会为该连接创建一个专用密钥，您可以像撤销其他密钥一样，在 /dashboard/keys 中撤销它。

3. 连接 Claude

Claude.ai 和 Claude Desktop。该服务器已收录在连接器目录中，因此最快的方式是打开 https://claude.ai/directory/listings-api 并点击 Connect（连接）。Claude 会启动 OAuth 流程，您批准作用域后，即可在任何聊天中通过 + 按钮再选择 Connectors（连接器）来启用该连接器，使用这些工具。

如果您希望通过 URL 添加，请依次进入 Customize（自定义）和 Connectors（连接器），点击 + 和 Add custom connector（添加自定义连接器），粘贴 https://listingsapi.com/mcp，然后点击 Add（添加）。将 Advanced settings（高级设置）留空；服务器会自动将 Claude 注册为客户端。在 Team 和 Enterprise 套餐中，所有者先在 Organization settings（组织设置）下的 Connectors（连接器）中添加连接器，之后成员再点击该连接器上的 Connect（连接）。Claude 从 Anthropic 的服务器发起连接，而非从您的计算机发起连接，因此需要使用托管服务的 URL。

Claude Code。一条命令即可使用您的密钥添加服务器：

Claude Code

claude mcp add --transport http listingsapi https://listingsapi.com/mcp \--header "Authorization: API $LISTINGSAPI_KEY"

如果要改为通过浏览器登录，请去掉 --header 标志，并在 Claude Code 中运行 /mcp。使用 --scope project 将服务器配置提交到整个团队共享的 .mcp.json 中；不要一并提交密钥。

4. 连接 ChatGPT

开启 Developer mode（开发者模式）后，ChatGPT 可以通过自定义连接器连接到远程 MCP 服务器。此功能适用于 Plus、Pro、Business、Enterprise 和 Edu 套餐，不适用于免费套餐。

从您的个人资料菜单中打开 Settings（设置），并开启 Developer mode（开发者模式）。根据版本的不同，此选项位于 Apps & Connectors（应用与连接器）或 Security and login（安全与登录）下。
在连接器页面（当前版本中标为 Plugins（插件））上，点击 + 或 Create（创建）。
输入名称，将 https://listingsapi.com/mcp 粘贴为服务器 URL，并选择 OAuth 作为身份验证方式。保存。
ChatGPT 会打开登录页面。批准 read 或 read write。
在新对话中，打开工具菜单，选择连接器，并确认其中显示了该连接器及其工具。执行写入操作的工具仍需通过确认提示才能运行。

Codex CLI。 OpenAI 的终端智能体从 ~/.codex/config.toml 读取 MCP 服务器配置。对于 HTTP 服务器，Codex 会自行启动 OAuth 流程，并遵循服务器声明的权限范围，因此请求头配置行是可选的：

~/.codex/config.toml

[mcp_servers.listingsapi]url = "https://listingsapi.com/mcp"http_headers = { "Authorization" = "API <your key>" }

5. 连接 Cursor

/dashboard/mcp 的控制台页面上有一个 Add to Cursor（添加到 Cursor）按钮。该按钮会打开一个 Cursor 安装链接，其中已填入服务器 URL 和您的密钥，因此点击一次即可完成设置。

要手动配置，请将服务器添加到 ~/.cursor/mcp.json，使其适用于所有项目；或者将其添加到某个仓库内的 .cursor/mcp.json：

~/.cursor/mcp.json

{"mcpServers": {  "listingsapi": {    "url": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    }  }}}

移除 headers 配置块即可改用 OAuth 登录：Cursor 会在 Settings（设置）下的 MCP 中，为该服务器条目显示一个 Connect（连接）按钮，并打开浏览器登录流程。切勿将密钥提交到项目级 .cursor/mcp.json 中；对于共享仓库，请使用全局文件或 OAuth。

6. 连接 Gemini

Gemini CLI。 Google 的终端智能体通过 ~/.gemini/settings.json（或项目中的 .gemini/settings.json）配置远程服务器。请使用 httpUrl，不要使用 url，以便选择 Streamable HTTP 传输方式：

~/.gemini/settings.json

{"mcpServers": {  "listingsapi": {    "httpUrl": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    },    "timeout": 30000  }}}

要使用 OAuth，请将 headers 配置块替换为 "oauth": { "enabled": true }，启动 CLI 并运行 /mcp auth listingsapi。您可以随时运行 /mcp，列出服务器、其连接状态以及发现的工具。

Gemini 应用。 面向消费者的 Gemini 应用没有自定义连接器设置。Gemini Enterprise Business 版的团队管理员可以使用自定义 MCP 服务器：在 business.gemini.google 登录，打开 Settings & help（设置与帮助），依次进入 Manage team（管理团队）和 Connected apps（已连接的应用），然后点击 Add MCP Server（添加 MCP 服务器）。将 https://listingsapi.com/mcp 粘贴为 URL。表单会要求填写 OAuth 详细信息：授权 URL 为 https://listingsapi.com/oauth/authorize，令牌 URL 为 https://listingsapi.com/oauth/token，权限范围为 read write。表单还会要求填写客户端 ID 和客户端密钥。此服务器签发的是不带密钥的公共 PKCE 客户端，因此请使用表单显示的重定向 URL 注册一个客户端，并在表单允许的情况下将密钥留空：

curl -s https://listingsapi.com/oauth/register \-H "Content-Type: application/json" \-d '{  "client_name": "Gemini Business",  "redirect_uris": ["<redirect URL shown in the Gemini form>"],  "grant_types": ["authorization_code", "refresh_token"],  "token_endpoint_auth_method": "none"}'

响应中包含 client_id。如果您的 Gemini 表单要求必须填写密钥，请改用上面的 Gemini CLI 方式，或使用 Gemini API 进行开发。

使用 Gemini API 开发。 Gemini API SDK 支持将 MCP 客户端会话作为工具传入，因此脚本可以为 Gemini 模型提供相同的工具：

gemini_agent.py

import asyncio, osfrom google import genaifrom mcp import ClientSessionfrom mcp.client.streamable_http import streamablehttp_client HEADERS = {"Authorization": "API " + os.environ["LISTINGSAPI_KEY"]} async def main():  gemini = genai.Client()  async with streamablehttp_client("https://listingsapi.com/mcp", headers=HEADERS) as (r, w, _):      async with ClientSession(r, w) as session:          await session.initialize()          reply = await gemini.aio.models.generate_content(              model="gemini-2.5-pro",              contents="Which of my locations have a Google listing that is not live yet?",              config=genai.types.GenerateContentConfig(tools=[session]),          )          print(reply.text) asyncio.run(main())

7. 验证连接

在依赖助手之前，请确认服务器能直接响应您的请求。工具发现不需要密钥，因此任何能够访问该 URL 的客户端都可以成功执行此调用：

List the tools

curl -s https://listingsapi.com/mcp \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

然后，在助手中提出一个必须访问您账户才能完成的请求：

使用 listingsapi 工具显示我的套餐，统计我的地点数量，并报告我本月的 API 用量。

连接正常时，whoami 会返回您的套餐和访问状态，locations_all 会返回地点数据，get_usage 会返回用量计数。密钥错误或过期时，首次调用工具会返回 Unauthenticated 错误，工具发现阶段不会返回此错误。

连接成功后，您可以先尝试以下提示词：

“列出存在商家信息错误的地点，并概述每个错误。”
“显示最近 7 天收到且尚未回复的评价，并为每条评价起草回复。暂时不要发送这些回复。”
“对比地点 1800289 最近 2 个月的 Google 商家资料分析数据。”
“阅读 create-location 端点的接口契约，然后添加此地点：……”

添加 listingsAPI 智能体技能

技能是一组指令，智能体会在任务匹配时加载这些指令，以便遵循经过验证的工作流程，而无需自行制定流程。技能与 MCP 服务器配合使用：服务器执行调用，技能决定调用哪些工具以及调用顺序。公开的 listingsapi-mcp 仓库中的 5 个 listingsAPI 技能已发布到 skills.sh：

技能	功能
`listingsapi-integration`	通过 REST 或 SDK 代码将 Listings API 集成到您的应用程序中：包括身份验证、首次读取、地点、发布平台连接和同步状态。
`listingsapi-listing-audit`	检查地点及其商家信息的同步状态、线上链接和疑似重复项，然后提出修复建议。在您批准修复前，仅执行只读操作。
`listingsapi-review-management`	建立评价队列，优先处理未回复的评价，起草回复，并且仅发布您批准的回复。
`listingsapi-multi-location-posting`	为您选择的多个地点准备公告、活动和优惠，并发布到 Google Business Profile 和 Facebook，然后逐一检查发布结果。
`listingsapi-performance-reporting`	为您的多个地点生成只读的绩效和评价报告。

使用 Skills CLI 将全部 5 个技能安装到您的项目中：

All skills

npx skills add listings-api/listingsapi-mcp

或者按名称安装单个技能，并使用 -a 选择智能体：

One skill, for Claude Code

npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-code

对于这些智能体，请使用 -a cursor 或 -a codex，并添加 -g，使安装对所有项目生效，而非仅对当前项目生效。

在 AI 工具目录中查找 listingsAPI

这些目录收录了同一个服务器以及 listingsAPI 智能体技能。请从您的客户端已在使用的目录中安装。每个 MCP 服务器条目都指向 https://listingsapi.com/mcp。

目录	收录内容
Claude 连接器目录	以 Claude 连接器形式提供的 MCP 服务器。点击 Connect（连接）并登录。
官方 MCP 注册表	MCP 服务器，注册名称为 `com.listingsapi/mcp`。
Cursor Directory	以 Cursor 插件形式提供的 MCP 服务器。
Glama	MCP 服务器。
Smithery	MCP 服务器。
MCP.so	MCP 服务器。
mcpservers.org	MCP 服务器。
ClawHub（OpenClaw）	listingsAPI 智能体技能。
skills.sh	listingsAPI 智能体技能。

故障排查

现象	原因	解决方法
首次调用工具时出现 `401`	密钥输入有误、已被撤销，或请求头未使用原样的 `API` 单词后接一个空格的格式	在 `/dashboard/keys` 中重新创建密钥，并按 `API <key>` 的格式粘贴
写入时出现 `SY90016`	使用了读取密钥或 `read` 权限范围	使用写入密钥重新连接，或批准 `write`
出现 `429`，并附带 `Retry-After`	智能体的调用频率超出了您的套餐限制	请让智能体分成更小的批次执行；参阅速率限制
客户端提示无法连接服务器	客户端仅支持 stdio 或 SSE	使用支持 Streamable HTTP 的客户端，或使用 `/dashboard/mcp` 中所示的 `mcp-remote` 桥接工具
找不到文档中提到的某个工具	未开放破坏性操作工具	使用 REST 或 SDK 执行归档和删除操作

后续步骤

选择集成方式：了解何时适合使用 MCP，以及何时选择 REST 或 SDK 更合适。
发起首次 API 调用：获取密钥，并了解工具返回的响应结构。
使用 webhook 响应事件：让平台通知您的智能体，无需轮询。
参阅身份验证和错误代码，了解助手向您报告的代码。