將 AI 代理程式連接至 listingsAPI MCP

將 Claude、ChatGPT、Cursor 或 Gemini 連接至託管的 MCP 伺服器，讓助理使用您會呼叫的相同工具，讀取您的地點、商家資訊和評論，並對其執行操作。

Listings API 在 https://listingsapi.com/mcp 提供 Model Context Protocol（MCP）伺服器。您不需要安裝或執行任何軟體。支援 MCP 的 AI 助理會連線至該 URL，取得每個 REST 端點對應的工具及幾個文件工具，並在您的帳號中呼叫這些工具。本指南會依序說明如何連線各個主要用戶端，再驗證連線。

1. 瞭解代理程式可使用的工具

伺服器提供 60 多個工具，其中約 3 分之 2 為唯讀工具。工具名稱依循 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。使用 1 個指令即可透過您的金鑰新增伺服器：

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 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 回應事件：讓平台通知您的代理程式，取代輪詢。
請參閱驗證與錯誤代碼，瞭解助理會向您回報的代碼。