Merchant API MCP Access Service (Alpha 版)

使用 Merchant API Model Context Protocol (MCP) 存取服務，取得 Merchant Center 資料和洞察資訊的授權存取權，建構新的代理體驗和自動化工作流程。

總覽

Merchant API MCP Access Service 提供標準化且安全的中介，讓 LLM、代理和程式碼輔助工具建構及自動化調度管理新的代理式體驗和自動化工作流程，並以 Merchant Center 資料為基礎。

具體來說，這項服務可授權存取你的 Merchant Center 資料和 Google 產生的報表與洞察資料，執行唯讀和有限的寫入作業，以解決下列用途：

  • 診斷及修正產品遭到拒登的問題
  • 產生成效報表和洞察資料
  • 查看自動改善功能的啟用狀態
  • 建立及擷取資料來源

安全和存取控管

Merchant API MCP Access Service 的設計以安全為優先考量：

  • 驗證：工具執行作業受標準 Merchant API 驗證控管，需要 OAuth 2.0 或服務帳戶憑證。建議您使用權限最嚴格的憑證。
  • 執行安全：雖然代理程式探索不會限制工具的顯示，但工具執行作業僅限使用特定 API 憑證。
  • 安全措施：工具僅限唯讀作業和低風險寫入工具 (例如建立資料來源)，做為安全防護措施。

重要注意事項

Merchant API MCP Access Service 為 Alpha 版，其範圍和功能將會擴大，且可能有所變更。

開始之前，請先詳閱下列限制和最佳做法：

變更和發布版本

如有異動，恕不另行事先通知，並會發布在版本資訊中。

安全測試

建議您先使用測試帳戶或非實際帳戶進行實驗，再於正式環境中使用這些工具。

共用配額

Merchant API MCP Access Service 與標準 Merchant API 呼叫共用相同的配額集區。執行代理程式會快速用盡配額，尤其是資料來源擷取作業。強烈建議使用測試帳戶，以免生產服務中斷。

篩選工具和安全性

日後會新增更多功能，尤其是寫入動作。 強烈建議您明確設定用戶端，使用內建工具篩選功能，而非公開整個工具集。

可用功能摘要

你可以使用 Merchant API MCP Access Service，以代理方式執行下列動作：

  • 使用確切的資源名稱，擷取特定產品的詳細狀態和報表內容。
  • 列出並搜尋多項產品。
  • 查詢成效指標、產品狀態，以及熱銷產品、定價分析、競爭曝光率和 YouTube Shopping 聯盟的數據分析洞察。
  • 找出會影響產品曝光度或計畫參與資格的帳戶層級問題。
  • 列出、建立、擷取及檢查資料來源的上傳狀態。
  • 列出商品目錄中產品遭拒登的匯總原因。
  • 查看商品、圖片和運送的自動改善設定。
  • 查看特定 Merchant Center 計畫的有效區域、未達成的規定和參與狀態。

開始使用

如要將 IDE、程式設計助理或代理程式連結至 Merchant API MCP Access Service，請更新 MCP 用戶端設定 (例如 mcp.json 或 settings.json)。

用戶端設定

設定：

Antigravity

使用 OAuth 2.0 存取權杖 (範圍為 https://www.googleapis.com/auth/content)，直接連線至代管的遠端 MCP 端點。請按照 Antigravity 說明文件中的操作說明進行。

{
    "mcpServers": {
        "merchant-api-access": {
            "serverUrl": "https://merchantapi.googleapis.com/mcp",
            "headers": {
                "Authorization": "Bearer {ACCESS_TOKEN}",
                "x-goog-user-project": "{GOOGLE_CLOUD_PROJECT_ID}"
            }
        }
    }
}

Claude CLI

使用 claude mcp add 指令，直接在 Claude CLI 中新增代管的遠端 MCP 端點：

claude mcp add --transport http merchant-api https://merchantapi.googleapis.com/mcp --scope local \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --header "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}"

請按照 Claude MCP 說明文件中的指示操作。

cURL

將標準 JSON-RPC 2.0 要求直接傳送至代管的 Merchant API MCP 端點。

可用工具清單：

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

執行工具呼叫 (例如 list_data_sources)：

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      }
    }
  }'

更改下列內容：

  • ACCOUNT_ID：你的 Merchant Center ID
  • ACCESS_TOKEN：用於發出 API 呼叫的授權權杖
  • GOOGLE_CLOUD_PROJECT_ID：與 Merchant Center 帳戶相關聯的 Google Cloud 雲端專案 ID

使用情境範例

為說明如何運用 Merchant API MCP Access Service 建構代理式體驗和自動化工作流程，請參考下列情境：

情境 1：診斷及修正產品遭拒登的問題

你想瞭解特定產品未顯示在 Google 搜尋結果中的原因。

使用者提示：

「Why is my product with offer ID 'offer123' disapproved?」(為什麼我的產品 (優惠 ID 為「offer123」) 遭到拒登？)

使用 MCP 時的服務專員行為：

  1. 代理程式會呼叫 list_products 或 get_product_by_name，找出產品狀態。
  2. MCP 伺服器會傳回產品狀態，包括錯誤清單 (例如「價格格式不正確」或「缺少運送值」)。issues
  3. 專員會分析問題並說明根本原因， 建議修正方式 (例如更新價格資訊)。

情境 2：查看自動改善功能的啟用狀態

你想確認運送服務自動改善功能是否已啟用。

使用者提示：

「我是否已啟用運送服務自動改善功能？」

使用 MCP 時的代理程式行為：

  1. 代理會呼叫 get_automatic_improvements，以擷取帳戶層級設定。
  2. MCP 伺服器會傳回設定，顯示圖片、項目和運送改善項目的狀態。
  3. 服務專員會確認運送改善功能是否已啟用，如果未啟用，則會說明如何啟用。

情境 3：產生成效報表和洞察資料

您想快速查看近期成效，不必瀏覽 Merchant Center 使用者介面。

使用者提示：

「顯示上週點擊次數前 5 名的產品。」

使用 MCP 時的代理程式行為：

  1. 代理程式會建構以 product_performance_view 資料表為目標的 Merchant Center 查詢語言 (MCQL) 查詢，並依 clicks DESC 排序，且限制為 5。
  2. 代理會使用建構的查詢呼叫 report_search。
  3. MCP 伺服器會針對即時報表資料庫執行查詢，並傳回資料列。
  4. 代理會將結果格式化為簡潔的 Markdown 表格。

情境 4：建立及擷取資料來源

你想新增資料來源，以便上傳產品更新。

使用者提示：

「為我的商家帳戶建立名為『price-updates』的補充資料來源。」

使用 MCP 時的服務專員行為：

  1. 代理程式會使用指定設定呼叫 create_data_source，以註冊新動態消息。
  2. MCP 伺服器會建立資料來源，並傳回專屬資源名稱。
  3. 代理程式會呼叫 fetch_data_source，觸發相關聯檔案的下載和處理作業。
  4. 代理會呼叫 get_file_upload 來監控上傳進度，並確認項目是否已成功處理。

MCP 工具和說明

Merchant API MCP Access Service 會向代理公開下列工具：

MCP 工具 說明
get_product_by_name 使用確切的產品資源名稱，取得特定商家的產品資訊。傳回詳細的產品狀態，包含報表背景資訊和潛在的產品層級問題。
list_products 列出或搜尋特定商家的多項產品。傳回詳細的產品狀態，其中包含多項產品的報表內容和潛在產品層級問題。
report_search 查詢報表表格，即可擷取產品成效指標、產品狀態、價格分析資料和競爭曝光率。詳情請參閱「報表指南」。
list_data_sources 列出特定商家可用的資料來源。
get_data_source 取得特定資料來源的詳細資料。
create_data_source 為特定商家建立新的資料來源。
fetch_data_source 擷取及處理與特定商家資料來源相關聯的檔案。
get_file_upload 取得特定資料來源的最新檔案上傳狀態。
list_accounts 列出特定使用者的帳戶。
list_account_issues 列出特定商家帳戶層級的問題，找出帳戶整體問題。
list_programs 列出特定商家適用的計畫，包括參與狀態、有效區域和任何未達成的規定。
list_aggregate_product_statuses 列出匯總的產品層級問題，監控產品資料的整體健康狀態。
get_automatic_improvements 取得自動改善設定，包括商品更新、圖片改善和運送服務改善。