將 AI 代理程式連接至 listingsAPI MCP

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

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

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

伺服器提供 60 多個工具,其中約 2/3 為唯讀工具。工具名稱依循 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_duplicateRead,標記重複項目需要 Write
已連結的帳戶connected_accounts_list, connected_accounts_listings, connected_accounts_connect_listingRead,連結和匯入需要 Write
評論reviews_list, reviews_get, reviews_respond, reviews_analyticsRead,回覆需要 Write
貼文posts_social_post_view, posts_create_socialRead,發布需要 Write
分析analytics_google、analytics_facebook、analytics_bing(已棄用,不會傳回資料)Read
帳戶whoami, get_usage, get_subscription, recent_errorsRead
文件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 writeClaude 和 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 方案,不適用於免費方案。

  1. 從您的個人資料選單開啟 Settings(設定),並開啟 Developer mode(開發人員模式)。依版本而定,此選項位於 Apps & Connectors(應用程式與連接器)或 Security and login(安全性與登入)之下。
  2. 在連接器頁面(目前版本標示為 Plugins(外掛程式))上,按一下 + 或 Create(建立)。
  3. 輸入名稱,貼上 https://listingsapi.com/mcp 作為伺服器 URL,並選擇 OAuth 作為驗證方式。儲存設定。
  4. ChatGPT 會開啟登入頁面。核准 read 或 read write。
  5. 在新對話中,開啟工具選單,選取連接器,並確認連接器及其工具皆已顯示。寫入工具仍需您確認後才能執行。

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)按鈕。此按鈕會開啟已填入伺服器 URL 和您金鑰的 Cursor 安裝連結,因此只需按一下即可完成設定。

若要手動設定,請將伺服器新增至 ~/.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 註冊一個用戶端,並在表單允許的情況下將密鑰欄位留空:

Register an OAuth client
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 伺服器。
GlamaMCP 伺服器。
SmitheryMCP 伺服器。
MCP.soMCP 伺服器。
mcpservers.orgMCP 伺服器。
ClawHub (OpenClaw)listingsAPI 代理程式技能。
skills.shlistingsAPI 代理程式技能。

疑難排解

狀況原因解決方式
首次呼叫工具時出現 401金鑰輸入錯誤、已撤銷,或標頭未使用 API 原文加上 1 個空格在 /dashboard/keys 中重新建立金鑰,並以 API <key> 格式貼上
寫入時出現 SY90016使用 Read 金鑰或 read 權限範圍使用 Write 金鑰重新連線,或核准 write
429 同時伴隨 Retry-After代理程式的呼叫頻率超過您的方案允許的上限請要求代理程式縮小每批處理的數量;請參閱速率限制
用戶端表示無法連線至伺服器用戶端僅支援 stdio 或 SSE使用支援 Streamable HTTP 的用戶端,或 /dashboard/mcp 上所示的 mcp-remote 橋接工具
找不到文件中提及的工具未提供破壞性操作工具使用 REST 或 SDK 執行封存和刪除操作

後續步驟