Merchant API MCP Access Service (Alpha)

Use the Merchant API Model Context Protocol (MCP) Access Service to get authorized access to your Merchant Center data and insights to build new agentic experiences and automated workflows.

Overview

The Merchant API MCP Access Service provides a standardized, secure bridge for LLMs, agents, and coding assistants to build and orchestrate new agentic experiences and automated workflows grounded in Merchant Center data.

Specifically, it allows authorized access to your Merchant Center data and Google-generated reports and insights to perform read-only and limited write operations to address use cases such as:

• Diagnose and fix product disapprovals
• Generate performance reports and insights
• Review the opt-in for automatic improvements
• Create and fetch data sources

Safety and access controls

The Merchant API MCP Access Service is designed with a priority on security:

• Authentication: Tool execution is governed by standard Merchant API authentication, requiring OAuth 2.0 or service account credentials. We recommend using credentials with the most restrictive access rights possible.
• Execution Safety: While tool visibility is not restricted for agentic discovery, tool execution is restricted to your specific API credentials.
• Safeguards: Tools are strictly limited to read-only operations and low-risk write tools (for example, data source creation) as a safety guardrail.

Important considerations

The Merchant API MCP Access Service is an alpha version; its scope and capabilities will be expanded and may change.

Before getting started, review the following limitations and best practices:

Changes and releases

Changes can happen without prior notice and will be published in the release notes.

Safe testing

We recommend experimenting first using a test account or a non-live account before utilizing these tools in a live production environment.

Shared quota

The Merchant API MCP Access Service shares the same quota pool as your standard Merchant API calls. Running agents can quickly exhaust quota, especially for data source fetches. We strongly recommend using a test account to prevent production service disruptions.

Tool filtering and safety

New capabilities, especially write actions, will be added in the future. We strongly recommend explicitly configuring your client to built-in tool filtering rather than exposing the entire toolset.

Summary of available capabilities

You can use the Merchant API MCP Access Service to perform the following actions in an agentic way:

• Retrieve detailed status and reporting context for specific products using exact resource names.
• List and search for multiple products.
• Query performance metrics, product statuses, and insights on popular products, pricing insights, competitive visibility, and YouTube Shopping Affiliate analytics.
• Identify account-level issues affecting product visibility or program participation.
• List, create, fetch, and check the upload status of data sources.
• List aggregated reasons for product disapprovals across your inventory.
• Review the automatic improvement settings for items, images, and shipping.
• Check the active regions, unmet requirements, and participation state for specific Merchant Center programs.

Getting started

To connect your IDE, coding assistant, or agent to the Merchant API MCP Access Service, update your MCP client settings (for example, mcp.json or settings.json).

Client configuration

Configuration setups:

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

Replace the following:

• ACCOUNT_ID: your Merchant Center ID
• ACCESS_TOKEN: the authorization token to make the API call
• GOOGLE_CLOUD_PROJECT_ID: the ID of the Google Cloud project associated with your Merchant Center account

Example usage scenarios

To illustrate how you can leverage the Merchant API MCP Access Service to build agentic experiences and automated workflows, consider the following scenarios:

Scenario 1: Diagnose and fix product disapprovals

You want to understand why a specific product is not showing up in Google Search results.

User prompt:

"Why is my product with offer ID 'offer123' disapproved?"

Agent behavior with MCP:

1. The agent calls list_products or get_product_by_name to locate the product status.
2. The MCP server returns the product status, including a list of issues (for example, "Incorrect price format" or "Missing shipping value").
3. The agent analyzes the issues and explains the root cause to you, suggesting how to fix it (for example, updating the price information).

Scenario 2: Review the opt-in for automatic improvements

You want to verify if your automatic shipping improvements are active.

User prompt:

"Are my automatic shipping improvements enabled?"

Agent behavior with MCP:

1. The agent calls get_automatic_improvements to retrieve the account-level settings.
2. The MCP server returns the configuration showing the status of image, item, and shipping improvements.
3. The agent confirms that shipping improvements are active, or explains how to enable them if they are off.

Scenario 3: Generate performance reports and insights

You want to quickly check your recent performance without navigating the Merchant Center UI.

User prompt:

"Show me my top 5 performing products by clicks last week."

Agent behavior with MCP:

1. The agent constructs a Merchant Center Query Language (MCQL) query targeting the product_performance_view table, ordering by clicks DESC and limiting to 5.
2. The agent calls report_search with the constructed query.
3. The MCP server executes the query against the live reporting database and returns the rows.
4. The agent formats the results into a clean Markdown table for you.

Scenario 4: Create and fetch data sources

You want to add a new data source to upload product updates.

User prompt:

"Create a supplemental data source named 'price-updates' for my merchant account."

Agent behavior with MCP:

1. The agent calls create_data_source with the specified settings to register the new feed.
2. The MCP server creates the data source and returns its unique resource name.
3. The agent calls fetch_data_source to trigger the download and processing of the associated file.
4. The agent calls get_file_upload to monitor the upload progress and confirm the successful processing status of the items.

MCP tools and descriptions

The Merchant API MCP Access Service exposes the following tools to your agent: