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 客户端设置。例如，更新 Google Agent Studio、Claude Desktop、Antigravity、Visual Studio Code 或自定义代理框架的 mcp.json 文件。

本地 Merchant API MCP Access Service 设置需要服务账号。此无头本地执行不支持标准用户 OAuth。您必须创建服务账号，下载其 JSON 私钥文件，并以实参的形式提供该文件的路径以及您的特定 Merchant Center ID。

如需详细了解如何创建和下载服务账号，请参阅服务账号指南。

客户端配置

配置设置：

Antigravity

按照 Antigravity 文档中的说明操作。

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

Claude Desktop

按照 Claude Desktop 文档中的说明操作。

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

使用场景示例

为了说明如何利用 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 Query Language (MCQL) 查询，该查询按 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 获取自动改进设置，包括商品更新、图片改进和配送改进。