通过 MCP 连接 AI 智能体

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

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

1. 了解智能体可使用的工具

服务器提供了 60 多个工具，其中约三分之二为只读工具。工具名称与 REST 资源保持一致，因此 locations_search、listings_premium、reviews_respond 和 posts_create_social 执行的操作与对应端点相同，参数和响应结构也相同。三个文档工具 search_docs、get_doc 和 get_endpoint 可让助手查阅页面或端点契约，而无需猜测载荷结构。

工具类别	示例	所需权限
地点	`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. 选择客户端的登录方式

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

方式	需要粘贴的内容	最适合
API 密钥请求头	将 `Authorization: API <your key>` 设为静态请求头	您可以控制配置文件的命令行工具和编辑器
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 返回的信息作答，提供您真实的账户 ID 和各项计数。密钥错误或过期会在首次工具调用时返回 Unauthenticated 错误，而不会在工具发现时返回。

连接正常后，可以先尝试以下提示词：

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

添加 listingsAPI 智能体技能

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

技能	功能
`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 密钥或 `read` 权限范围	使用 Write 密钥重新连接，或批准 `write`
出现 `429`，同时伴有 `Retry-After`	智能体的调用频率超过了您的套餐允许的上限	请让智能体分成更小的批次处理；参阅速率限制
客户端提示无法连接到服务器	客户端仅支持 stdio 或 SSE	使用支持 Streamable HTTP 的客户端，或使用 `/dashboard/mcp` 上展示的 `mcp-remote` 桥接工具
文档中提到的某个工具缺失	破坏性工具未对外提供	使用 REST 或 SDK 执行归档和删除操作

后续步骤

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