Merchant API MCP Access Service（Alpha 版）

使用 Merchant API Model Context Protocol (MCP) Access Service，以授权方式访问 Merchant Center 数据和分析洞见，从而构建新的智能体体验和自动化工作流。

概览

Merchant API MCP Access Service 为大语言模型、智能体和编码助理提供了一个标准化、安全的桥梁，以便它们基于 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）。

客户端配置

配置设置：

{
    "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}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

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}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: list_data_sources" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

使用场景示例

为了说明如何利用 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 会向您的智能体提供以下工具：