merchant-center-mcp

MCP server for Google Merchant Center diagnostics via the Merchant API v1 (gRPC): account info, feed/datasource status, and catalog reports via Merchant Center Query Language (MCQL). Read-only — no tool can modify a live catalog.

Tools (4)

⚠️ Reports API scope note: it only works on standalone accounts or individual sub-accounts, not on "advanced" (aggregator/MCA) accounts.

⚠️ MCQL limitation: the repeated field item_issues can't be filtered in a WHERE clause. get_product_issues works around this by pulling product_view and filtering client-side in Python (capped at 5000 scanned rows by default).

Related MCP server: Google Ads MCP

Setup

1. Create a Google Cloud project (or reuse one) and enable the Merchant API.

2. Create an OAuth 2.0 Client ID of type "Desktop app" and download it as client_secret.json.

3. If the app is in "Testing" mode, add your Google account as a test user.

4. Install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

5. Run the OAuth flow once:

   CLIENT_SECRET_PATH=~/.config/merchant-center-mcp/client_secret.json python3 setup_auth.py

   This opens a browser — log in and grant access. The token is saved to ~/.config/merchant-center-mcp/token.json by default (set TOKEN_OUT to use a different path for a second account).

MCP client configuration

{
  "mcpServers": {
    "merchant-center": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/merchant-center-mcp/server.py"]
    }
  }
}

For a second account, point a second server instance at the token file you generated with TOKEN_OUT=~/.config/merchant-center-mcp/token_other.json.

Security

• All tools carry the MCP spec's Tool Annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true) — accurate, since this server never writes anything.

• Execution errors propagate as real MCP protocol errors (isError=true), never as a JSON payload disguised as a success response.

Notes

• Gone in favor of Merchant API v1: the Content API for Shopping it replaces was sunset in 2026. If you're still targeting the old API, this server won't help — migrate first.

• search_report/get_product_issues paginate through the gRPC response stream and stop once limit rows are collected — they don't fetch the whole result set up front.

License

MIT — see LICENSE.