Google Merchants MCP Server

Google Merchant Center MCP

MCP server for Google Merchant Center via the Merchant API v1: manage your product feed, promotions and data sources, run MCQL reports, check price competitiveness and product issues — from Claude, Cursor, Codex and other AI clients in natural language.

Unlike read-only integrations, this server authenticates with your own OAuth credentials and supports write operations: upload and delete products, insert promotions and trigger feed re-fetches — with destructive tools clearly annotated so MCP hosts can gate them.

Quick start

1. Get OAuth credentials for the Merchant API.

2. Add the server — for example in Claude Code (other clients):

   claude mcp add google-merchants \
     -e GOOGLE_MERCHANTS_CLIENT_ID=your_client_id \
     -e GOOGLE_MERCHANTS_CLIENT_SECRET=your_client_secret \
     -e GOOGLE_MERCHANTS_REFRESH_TOKEN=your_refresh_token \
     -e GOOGLE_MERCHANTS_ACCOUNT_ID=your_merchant_id \
     -- npx -y mcp-google-merchants
   

3. Ask the assistant: "Which of my products are disapproved, and why?"

What it can do

Resilience: retries with backoff on 429 and on 5xx/network errors for reads (writes are never replayed), Retry-After support, request timeouts, automatic access-token refresh.

Example prompts

• "List my Merchant Center products that are out of stock"
• "Why is product sku-123 disapproved in Shopping ads?"
• "Upload a test product 'Blue Widget' for $9.99 to my API feed"
• "Which of my products are priced above the market benchmark in the US?"
• "Show clicks and impressions per product for July"

MCQL examples

search_reports accepts raw Merchant Center Query Language. Field names are snake_case in queries and camelCase in responses; SELECT * is not supported; performance views require a date range.

-- Filter products (list_products has no filter — this is the way)
SELECT offer_id, title, price, aggregated_reporting_context_status
FROM product_view
WHERE aggregated_reporting_context_status = 'NOT_ELIGIBLE_OR_DISAPPROVED'

-- Performance over a date range
SELECT offer_id, title, clicks, impressions, click_through_rate
FROM product_performance_view
WHERE date BETWEEN '2026-07-01' AND '2026-07-31'
ORDER BY clicks DESC

-- Price competitiveness (requires the free Market Insights opt-in)
SELECT offer_id, title, price, benchmark_price
FROM price_competitiveness_product_view
WHERE report_country_code = 'US'

API access

The server talks to the Merchant API v1 (merchantapi.googleapis.com) — the successor of the Content API for Shopping (sunset in August 2026). Auth is standard Google OAuth 2.0 with the scope https://www.googleapis.com/auth/content; the server exchanges your refresh token for access tokens automatically.

One-time registration required. Before any Merchant API call works, your Google Cloud project must be registered with the Merchant Center account once (needs Admin access):

raw_request POST accounts/v1/accounts/{account}/developerRegistration:registerGcp
body: {"developerEmail": "you@example.com"}

You can do it right from the assistant with the raw_request tool, or with any HTTP client. Until then every call fails with a permission error.

Installation

claude mcp add google-merchants \
  -e GOOGLE_MERCHANTS_CLIENT_ID=your_client_id \
  -e GOOGLE_MERCHANTS_CLIENT_SECRET=your_client_secret \
  -e GOOGLE_MERCHANTS_REFRESH_TOKEN=your_refresh_token \
  -e GOOGLE_MERCHANTS_ACCOUNT_ID=your_merchant_id \
  -- npx -y mcp-google-merchants

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\

{
  "mcpServers": {
    "google-merchants": {
      "command": "npx",
      "args": ["-y", "mcp-google-merchants"],
      "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.json (or .cursor/mcp.json in a project)

{
  "mcpServers": {
    "google-merchants": {
      "command": "npx",
      "args": ["-y", "mcp-google-merchants"],
      "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"
      }
    }
  }
}

.vscode/mcp.json — note the servers key (not mcpServers)

{
  "servers": {
    "google-merchants": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-merchants"],
      "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"
      }
    }
  }
}

Getting access

1. Create (or pick) a Google Cloud project at console.cloud.google.com and enable the Merchant API (APIs & Services → Library → "Merchant API" → Enable).

2. Configure the OAuth consent screen (APIs & Services → OAuth consent screen): External, fill in the app name and your email, and add yourself as a test user (Testing mode is fine for personal use).

3. Create an OAuth client (APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app). Save the client ID and client secret.

4. Mint a refresh token for the scope https://www.googleapis.com/auth/content. The quickest way is the OAuth 2.0 Playground:

   • click the gear icon → check Use your own OAuth credentials → paste your client ID/secret;
   • in Step 1 enter the scope https://www.googleapis.com/auth/content and authorize with the Google account that has access to your Merchant Center;
   • in Step 2 click Exchange authorization code for tokens and copy the refresh token.

   (Any other flow works too — the server only needs the resulting refresh token. For quick experiments you can instead pass a short-lived access token as GOOGLE_MERCHANTS_ACCESS_TOKEN, e.g. from gcloud auth print-access-token.)

5. Find your Merchant Center ID — the number in the top-right corner of merchants.google.com — and put it in GOOGLE_MERCHANTS_ACCOUNT_ID (or pass account per tool call, or discover it with list_accounts).

6. Register your GCP project with the Merchant Center account (one-time, Admin access required) — see API access.

⚠️ Credentials are stored in plain text in your MCP client config — treat them like passwords. The refresh token grants full read/write access to your Merchant Center.

Configuration

* Either the client ID + secret + refresh token trio, or a bare access token.

Requirements

• Node.js 20+ (runs via npx, no separate install needed).
• A Merchant Center account and a registered Google Cloud project — see Getting access.

Limitations

• Product writes are asynchronous. After insert_product_input / delete_product_input the processed product updates within minutes — an immediate get_product may 404 or show stale data. Data-quality problems appear later in productStatus.itemLevelIssues, not as API errors.
• price_competitiveness / price_insights return rows only for accounts opted into Market Insights (free, in Merchant Center settings).
• list_product_issues works for sub-accounts and standalone accounts only, not for advanced (parent) accounts.
• Quotas are per-account with daily counters resetting at 12:00 UTC (midday). Check your current usage with list_method_quotas.

Documentation

• All tools — full list with details.
• Development — build, tests, smoke check.
• Publishing — releases and MCP registry listing.

Support

Questions, ideas and contributions — Telegram: @gistrec or GitHub issues.

License

MIT — see LICENSE.