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 Access Service 是 Alpha 版；其范围和功能将会扩展，并且可能会发生变化。

开始之前，请查看以下限制和最佳实践：

更改和发布

更改可能会在未事先通知的情况下发生，并且会在版本说明中发布。

安全测试

我们建议您先使用 测试账号或非正式 账号进行实验，然后再在正式生产环境中使用这些工具。

共享配额

Merchant API MCP Access Service 与标准 Merchant API 调用共享同一配额池。运行智能体可能会快速耗尽配额，尤其是在提取数据源时。我们强烈建议您使用测试账号，以防止生产服务中断。

工具过滤和安全性

我们日后会添加新功能，尤其是写入操作。 我们强烈建议您将客户端明确配置为 内置工具过滤，而不是公开整个 工具集。

可用功能摘要

您可以使用 Merchant API MCP Access Service 以智能体方式执行以下操作：

  • 使用确切的资源名称检索 指定商品的详细状态和报告上下文。
  • 列出和搜索 多个商品。
  • 查询 效果指标、商品状态以及热门商品、价格分析、竞争对手的曝光度、YouTube 购物联属营销分析洞见。
  • 识别 影响商品可见性或计划参与度的账号级问题。
  • 列出、创建、提取和检查 数据源的上传状态。
  • 列出 整个商品目录中商品拒批的汇总原因。
  • 查看 商品、图片和配送的自动优化设置。
  • 检查 特定 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 搜索结果中。

用户提示：

“为什么我的商品（优惠 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. 智能体构建一个 Merchant Center 查询语言 (MCQL) 查询 ，以 product_performance_view 表为目标，按 clicks DESC 排序，并限制为 5。
  2. 智能体使用构建的查询调用 report_search。
  3. MCP 服务器针对实时报告数据库执行查询，并返回行。
  4. 智能体将结果格式化为简洁的 Markdown 表格，供您查看。

场景 4：创建和提取数据源

您想添加新的数据源来上传商品更新。

用户提示：

“为我的商家账号创建一个名为 'price-updates' 的补充数据源。”

使用 MCP 的智能体行为：

  1. 智能体使用指定的设置调用 create_data_source 来注册新的 Feed。
  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 获取自动优化设置，包括商品更新、图片优化和配送优化。