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.

> [!WARNING]
> **Experimental:** This feature is an experimental alpha version subject to change at any time without prior notice. We don't recommend using these features for sensitive systems with high reliability needs.

## 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](https://developers.google.com/merchant/api/guides/quickstart/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](https://developers.google.com/merchant/api/guides/accounts/test-accounts) 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](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1300) 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:

### Antigravity

Connect directly to the hosted remote MCP endpoint using an OAuth 2.0 access
token (with scope `https://www.googleapis.com/auth/content`). Follow
instructions in the
[Antigravity documentation](https://antigravity.google/docs/mcp).

    {
        "mcpServers": {
            "merchant-api-access": {
                "serverUrl": "https://merchantapi.googleapis.com/mcp",
                "headers": {
                    "Authorization": "Bearer {ACCESS_TOKEN}",
                    "x-goog-user-project": "{GOOGLE_CLOUD_PROJECT_ID}"
                }
            }
        }
    }

Replace the following:

- <var translate="no">`ACCESS_TOKEN`</var>: the authorization token to make the API call
- <var translate="no">`GOOGLE_CLOUD_PROJECT_ID`</var>: the ID of the Google Cloud project associated with your Merchant Center account

### Claude CLI

Add the hosted remote MCP endpoint directly in Claude CLI using the
`claude mcp add` command:

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

Replace the following:

- <var translate="no">`ACCESS_TOKEN`</var>: the authorization token to make the API call
- <var translate="no">`GOOGLE_CLOUD_PROJECT_ID`</var>: the ID of the Google Cloud project associated with your Merchant Center account

Follow instructions in the [Claude MCP
documentation](https://docs.anthropic.com/en/docs/agents-and-tools/mcp).

### cURL

Send standard JSON-RPC 2.0 requests directly to the hosted Merchant API MCP
endpoint.

**List available tools:**

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

**Execute a tool call (for example, `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}" \
      -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}"
          }
        }
      }'

Replace the following:

- <var translate="no">`ACCOUNT_ID`</var>: your Merchant Center ID
- <var translate="no">`ACCESS_TOKEN`</var>: the authorization token to make the API call
- <var translate="no">`GOOGLE_CLOUD_PROJECT_ID`</var>: the ID of the Google Cloud project associated with your Merchant Center account
- <var translate="no">`MCP_PROTOCOL_VERSION`</var>: the MCP protocol version, for example, `2026-07-28`

> [!NOTE]
> **Note:** The `x-goog-user-project` (or `X-Goog-User-Project`) header specifies your Google Cloud Project ID for quota attribution. Providing this header is **required when using User Application Default Credentials (ADC)**. It is not required when authenticating with a Service Account private key or a standard OAuth 2.0 Client ID.

## 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:

| MCP Tool | Description |
|---|---|
| `get_product_by_name` | Get product info for a given merchant using the exact product resource name. Returns the detailed product status containing reporting context and potential product-level issues. |
| `list_products` | List or search for multiple products for a given merchant. Returns the detailed product status containing reporting context and potential product-level issues for multiple products. |
| `report_search` | Query reporting tables to retrieve product performance metrics, product statuses, price insights, and competitive visibility. See the [Reports guide](https://developers.google.com/merchant/api/guides/reports/overview) for details. |
| `list_data_sources` | List available data sources for a given merchant. |
| `get_data_source` | Get details of a specific data source. |
| `create_data_source` | Create a new data source for a given merchant. |
| `fetch_data_source` | Fetch and process the file associated with a data source for a given merchant. |
| `get_file_upload` | Get the status of the latest file upload for a given data source. |
| `list_accounts` | List accounts for a given user. |
| `list_account_issues` | List account-level issues for a given merchant to identify account-wide problems. |
| `list_programs` | List programs for a given merchant, including participation state, active regions, and any unmet requirements. |
| `list_aggregate_product_statuses` | List aggregated product-level issues to monitor the overall health of your product data. |
| `get_automatic_improvements` | Get automatic improvements settings, including item updates, image improvements, and shipping improvements. |