Merchant API MCP Access Service (Alpha 版)

使用 Merchant API Model Context Protocol (MCP) Access Service，取得 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 存取服務為 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)。

用戶端設定

設定配置：

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

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}"

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": {}
  }'

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 搜尋結果中的原因。

使用者提示：

「為什麼我的產品 (優惠 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 會向代理公開下列工具：