Merchant API MCP Access Service（Alpha 版）

使用 Merchant API Model Context Protocol (MCP) Access Service 获得对 Merchant Center 数据和分析洞见的授权访问权限，以构建新的代理式体验和自动化工作流。

实验性： 此功能为实验性 Alpha 版，可能会在未事先通知的情况下随时发生变化。对于需要高可靠性的敏感系统，我们不建议使用这些功能。

概览

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

直接向托管的 Merchant API MCP 端点发送标准 JSON-RPC 2.0 请求。

列出可用工具：

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

注意： x-goog-user-project（或 X-Goog-User-Project）标头用于指定您的 Google Cloud 项目 ID，以便进行配额归因。使用用户应用默认凭据 (ADC) 时，必须提供此标头。如果使用服务账号私钥或标准 OAuth 2.0 客户端 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 表为目标、按 clicks DESC 排序并限制为 5 的 Merchant Center Query Language (MCQL) 查询。
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	获取自动改进设置，包括商品更新、图片改进和配送改进。