mcp-google-merchants

# <img src="./assets/a1-logo.svg" alt="A1" width="40"> Google Merchant Center MCP

**English** | [Русский](./README.ru.md)

[![npm](https://img.shields.io/npm/v/mcp-google-merchants)](https://www.npmjs.com/package/mcp-google-merchants)
[![CI](https://github.com/A1-x-Tech/mcp-google-merchants/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-google-merchants/actions/workflows/ci.yml)
[![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-merchants/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-google-merchants)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

**A1 Google Merchant Center MCP** connects an AI app to your Google Merchant Center account. Find out why products are disapproved, inspect feeds and promotions, explore reports and market prices, then make deliberate changes to product data when you need to.

It works with the Merchant Center data behind Shopping listings: products, data sources, promotions and reports. Campaigns, budgets and bids belong to Google Ads and are outside this server.

- **22 tools.** 15 operations only read Merchant Center data; 5 write product, data-source or promotion data; 2 are potentially destructive.
- **Your Google access.** The server uses your OAuth credentials and the Merchant API v1 — it does not create a separate Merchant Center account.
- **Source-aware changes.** Product and promotion inputs can be changed only through an API data source. A file feed can be re-fetched, but its contents are not edited here.
- **Visible boundaries.** Tools carry read-only, write or destructive metadata, so an AI client can distinguish an inspection from a live change.

Start with a read-only question:

> Which products are disapproved, and what issues does Google report for each?

[Connect the server](#quick-start) · [Explore use cases](#what-you-can-ask-it-to-do) · [Open technical documentation](#technical-documentation)

---

## See it work in a minute

> **You:** Which products are disapproved, and what issues does Google report for each?
>
> **Assistant:** Lists the affected products and explains the item-level issues that Merchant Center reports.
>
> **You:** Show the current price and availability of product `SKU-123`, then prepare an availability update to `in_stock`.
>
> **Assistant:** Shows the current product input, the API data source it belongs to and the exact change to make. It asks for confirmation before updating the live product input.
>
> **You:** Confirm the update.
>
> **Assistant:** Sends the update and explains that Merchant Center processes product data asynchronously. The processed product and its quality status can take several minutes to refresh.

## Contents

- [Quick start](#quick-start)
- [What you can ask it to do](#what-you-can-ask-it-to-do)
- [How Merchant Center data is connected](#how-merchant-center-data-is-connected)
- [What can change](#what-can-change)
- [Getting access](#getting-access)
- [Configuration](#configuration)
- [Data and telemetry](#data-and-telemetry)
- [Limits and background work](#limits-and-background-work)
- [Technical documentation](#technical-documentation)
- [Support](#support)

## Quick start

You need Node.js 20+, a Google Merchant Center account, OAuth credentials from Google Cloud and a Google Cloud project registered with Merchant Center. The access setup is described in [Getting access](#getting-access).

1. Prepare the four values: OAuth client ID, OAuth client secret, OAuth refresh token and Merchant Center account ID.
2. Add the server to your AI app using one of the instructions below.
3. Ask the first read-only question above.

<details open>
<summary><strong>Codex</strong></summary>

<br>

**In the app:**

1. Open **Settings → Plugins → MCP servers**.
2. Select **Add server**.
3. Add the launch command `npx -y mcp-google-merchants@latest` and the four environment variables below.

| Variable | Value |
|---|---|
| `GOOGLE_MERCHANTS_CLIENT_ID` | Your Google OAuth client ID |
| `GOOGLE_MERCHANTS_CLIENT_SECRET` | Your Google OAuth client secret |
| `GOOGLE_MERCHANTS_REFRESH_TOKEN` | Your Google OAuth refresh token |
| `GOOGLE_MERCHANTS_ACCOUNT_ID` | Your Merchant Center account ID |

**From the command line:**

```bash
codex mcp add google-merchants \
  --env GOOGLE_MERCHANTS_CLIENT_ID=your_client_id \
  --env GOOGLE_MERCHANTS_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_MERCHANTS_REFRESH_TOKEN=your_refresh_token \
  --env GOOGLE_MERCHANTS_ACCOUNT_ID=your_merchant_id \
  -- npx -y mcp-google-merchants@latest
```

Check the connection:

```bash
codex mcp list
```

[Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)

</details>

<details>
<summary><strong>Claude Code</strong></summary>

<br>

```bash
claude mcp add \
  --env GOOGLE_MERCHANTS_CLIENT_ID=your_client_id \
  --env GOOGLE_MERCHANTS_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_MERCHANTS_REFRESH_TOKEN=your_refresh_token \
  --env GOOGLE_MERCHANTS_ACCOUNT_ID=your_merchant_id \
  --transport stdio \
  --scope user \
  google-merchants \
  -- npx -y mcp-google-merchants@latest
```

Check the connection:

```bash
claude mcp list
```

[Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

<br>

1. Open Claude Desktop and go to **Settings → Developer**.
2. Select **Edit Config**.
3. Add the server to `mcpServers`:

```json
{
  "mcpServers": {
    "google-merchants": {
      "command": "npx",
      "args": ["-y", "mcp-google-merchants@latest"],
      "env": {
        "GOOGLE_MERCHANTS_CLIENT_ID": "your_client_id",
        "GOOGLE_MERCHANTS_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_MERCHANTS_REFRESH_TOKEN": "your_refresh_token",
        "GOOGLE_MERCHANTS_ACCOUNT_ID": "your_merchant_id"
      }
    }
  }
}
```

If **Edit Config** is unavailable, open the configuration file directly:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

[Claude Desktop MCP documentation](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)

</details>

<details>
<summary><strong>Cursor</strong></summary>

<br>

Add a user-level server to `~/.cursor/mcp.json` on macOS/Linux or `%USERPROFILE%\.cursor\mcp.json` on Windows:

```json
{
  "mcpServers": {
    "google-merchants": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-merchants@latest"],
      "env": {
        "GOOGLE_MERCHANTS_CLIENT_ID": "your_client_id",
        "GOOGLE_MERCHANTS_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_MERCHANTS_REFRESH_TOKEN": "your_refresh_token",
        "GOOGLE_MERCHANTS_ACCOUNT_ID": "your_merchant_id"
      }
    }
  }
}
```

[Cursor MCP documentation](https://cursor.com/docs/mcp)

</details>

<details>
<summary><strong>VS Code</strong></summary>

<br>

Run **MCP: Open User Configuration** from the Command Palette and add:

```json
{
  "servers": {
    "google-merchants": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-merchants@latest"],
      "env": {
        "GOOGLE_MERCHANTS_CLIENT_ID": "${input:google_merchants_client_id}",
        "GOOGLE_MERCHANTS_CLIENT_SECRET": "${input:google_merchants_client_secret}",
        "GOOGLE_MERCHANTS_REFRESH_TOKEN": "${input:google_merchants_refresh_token}",
        "GOOGLE_MERCHANTS_ACCOUNT_ID": "${input:google_merchants_account_id}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "google_merchants_client_id",
      "description": "Google OAuth client ID"
    },
    {
      "type": "promptString",
      "id": "google_merchants_client_secret",
      "description": "Google OAuth client secret",
      "password": true
    },
    {
      "type": "promptString",
      "id": "google_merchants_refresh_token",
      "description": "Google OAuth refresh token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "google_merchants_account_id",
      "description": "Merchant Center account ID"
    }
  ]
}
```

Check the server with **MCP: List Servers**.

[VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

</details>

## What you can ask it to do

### Find and understand catalog problems

- Which products are disapproved, and what does Google report for each of them?
- Show the title, price, availability and current status of product `SKU-123`.
- Which products are out of stock?
- Show the most frequent product issues for this Merchant Center account.

### Explore performance and prices

- Show clicks and impressions by product for July.
- Which products are priced above the market benchmark in the United States?
- What prices does Google suggest, and what impact does it predict?

Price comparisons and suggestions require the free Market Insights opt-in in Merchant Center. If the account has not opted in, the server explains why the report has no rows.

### Inspect the account and feeds

- List the Merchant Center accounts I can access.
- Is the store homepage claimed? Show the current shipping settings.
- List the product and promotion data sources, and identify an API data source.
- Re-fetch this scheduled file feed now.

### Make deliberate changes

- Update the price and availability of this product in its API data source.
- Create an API data source for a new product feed.
- Create or update a promotion and then check its approval status.

For any request that changes data, first ask the assistant to show the target account, data source and exact fields it plans to change.

## How Merchant Center data is connected

Merchant Center keeps the incoming data and the resulting product status separate:

1. An **account** contains product and promotion data sources.
2. A **data source** can be an API source, a file, a Google Sheet, the Merchant Center interface o