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

| Tool | What it does |
|---|---|
| `get_account` | Basic account info (name, ID, language, timezone, test flag) |
| `list_datasources` | Feeds configured on the account (primary, supplemental, local inventory...) |
| `search_report` | Run an MCQL query against any Reports API view (`product_view`, `product_performance_view`, `price_competitiveness_product_view`, `best_sellers_*`...) |
| `get_product_issues` | Shortcut over `search_report` for the most common QA task: products with active issues (rejected, warnings) |

⚠️ **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).

## 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:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   ```
5. Run the OAuth flow once:
   ```bash
   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

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

| Env var | Default | Purpose |
|---|---|---|
| `GOOGLE_MERCHANT_TOKEN_PATH` | `~/.config/merchant-center-mcp/token.json` | Path to the token file generated by `setup_auth.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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#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](LICENSE).