透過 MCP 連結 AI 代理程式

讓 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 的功能與對應端點相同，參數和回應結構也相同。3 個文件工具 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>` 設為靜態標頭	您可控制設定檔的 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 的結果，回答您實際的帳戶 ID 和數量。金鑰錯誤或過期時，第一次呼叫工具就會傳回 Unauthenticated 錯誤，而不是在探索工具時。

連線成功後，可先嘗試以下提示詞：

「列出我的地點中有商家資訊錯誤的地點，並摘要說明每個錯誤。」
「顯示最近 7 天內收到且尚未回覆的評論，並為每則評論草擬回覆。暫時不要送出回覆。」
「比較地點 1800289 最近 2 個月的 Google 商家檔案分析資料。」
「閱讀建立地點端點的規格，然後新增此地點：……」

新增 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 Registry	註冊名稱為 `com.listingsapi/mcp` 的 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 回應事件：讓平台通知您的代理程式，無須輪詢。
如需了解助理會向您回報的代碼，請參閱驗證與錯誤代碼。