# google-ecommerce-mcp

<!-- mcp-name: io.github.MoonEyes/google-ecommerce-mcp -->

One read-only MCP server for the Google services an online shop lives on: **GA4, Search Console, Merchant Center, Tag Manager, Indexing API and PageSpeed**.

Ask your AI assistant "how much organic traffic did we get this month?", "which products are disapproved in Merchant Center?" or "is GA4 loaded twice on my site?" and it answers from your own Google accounts.

Built by [MoonEyes](https://www.mooneyeswargame.com), a small French shop selling 3D-printed tabletop terrain, because no existing MCP server covered GA4, Search Console and Merchant Center together.

![tests](https://github.com/MoonEyes/google-ecommerce-mcp/actions/workflows/tests.yml/badge.svg)
![license](https://img.shields.io/badge/license-MIT-blue)
![python](https://img.shields.io/badge/python-3.10%2B-blue)
[![PyPI](https://img.shields.io/pypi/v/google-ecommerce-mcp)](https://pypi.org/project/google-ecommerce-mcp/)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.MoonEyes%2Fgoogle--ecommerce--mcp-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.MoonEyes/google-ecommerce-mcp)

![Architecture overview](https://raw.githubusercontent.com/MoonEyes/google-ecommerce-mcp/main/docs/diagrams/architecture-overview.png)

## Documentation

| Page | What is in it |
|---|---|
| [Architecture](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/docs/ARCHITECTURE.md) | Components, a tool call step by step, design choices, sequence diagrams |
| [Tool reference](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/docs/TOOLS.md) | Every tool: parameters, output, example questions |
| [Google Cloud setup](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/docs/SETUP-GOOGLE-CLOUD.md) | OAuth client, APIs to enable, where to find each id |
| [Security model](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/docs/SECURITY.md) | Scopes, token storage, threats, how to revoke |
| [Troubleshooting](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/docs/TROUBLESHOOTING.md) | Every error we have met and its fix |
| [Example prompts](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/examples/PROMPTS.md) | Questions that work well, by use case |
| [Client configs](https://github.com/MoonEyes/google-ecommerce-mcp/tree/main/examples) | Claude Desktop (one or two shops), Claude Code |

## Why this one

- **All-in-one for e-commerce.** Other MCP servers cover one or two of these services. This one covers the six a shop owner checks every week.
- **Read-only by design.** No tool creates, updates, publishes or deletes anything. A test enforces it.
- **Token in your OS keyring.** The OAuth token goes to Windows Credential Manager, macOS Keychain or Secret Service, not to a plain file (a file is still possible if you prefer).
- **Answers a model can read correctly.** Reports return the top rows plus totals over everything, the unit and definition of each metric, and dates resolved in the property's timezone with a flag when the last days can still change.
- **No third party.** Requests go straight from your machine to Google.

## Tools

| Tool | Service | What it answers |
|---|---|---|
| `server_status` | All | Which services are configured, does the token work |
| `ga4_report` | GA4 | Any report: channels, landing pages, purchases, revenue, by period |
| `ga4_realtime` | GA4 | Last 30 minutes, e.g. to check a page view is counted once |
| `ga4_properties` | GA4 | Every GA4 account and property you can read, to find a property id |
| `gsc_performance` | Search Console | Clicks, impressions, CTR, position by query, page, country, device, date |
| `gsc_inspect_url` | Search Console | Is this URL indexed, which canonical did Google pick, last crawl |
| `gsc_sitemaps` | Search Console | Declared sitemaps, last download, errors |
| `merchant_data_sources` | Merchant Center | Feeds, labels, countries, fetch URLs |
| `merchant_product_issues` | Merchant Center | Products with disapprovals or warnings, all pages |
| `merchant_report_query` | Merchant Center | Any Merchant Query Language report |
| `gtm_inventory` | Tag Manager | Tags, triggers, variables, live version |
| `indexing_status` | Indexing API | What Google knows about a submitted URL |
| `pagespeed` | PageSpeed Insights | Lighthouse performance and SEO scores, Core Web Vitals |

## Quick install

Create your Google OAuth client first ([step 1 below](#1-google-cloud-once-about-10-minutes)), then run one line. The installer installs [uv](https://docs.astral.sh/uv/) if needed, asks your ids, opens the Google consent screen and adds the server to Claude Desktop (your previous config is backed up).

**Windows** (PowerShell):

```powershell
irm https://raw.githubusercontent.com/MoonEyes/google-ecommerce-mcp/main/install.ps1 | iex
```

**macOS / Linux**:

```bash
curl -LsSf https://raw.githubusercontent.com/MoonEyes/google-ecommerce-mcp/main/install.sh | sh
```

Then quit Claude Desktop completely and reopen it. Prefer to read a script before running it? Download it, read it, then run it with options, for example `.\install.ps1 --ga4 123456789 --gsc sc-domain:example.com --client-secret client_secret.json`. Run `google-ecommerce-mcp install --help` for every option.

## Setup, step by step

If you used the quick install, you only need step 1. The steps below are the manual path.

### 1. Google Cloud (once, about 10 minutes)

Full walkthrough with every click explained: [docs/SETUP-GOOGLE-CLOUD.md](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/docs/SETUP-GOOGLE-CLOUD.md). Short version:

1. In [Google Cloud Console](https://console.cloud.google.com/), create or pick a project.
2. Enable the APIs you need: *Google Analytics Data API*, *Google Analytics Admin API*, *Google Search Console API*, *Merchant API*, *Tag Manager API*, *Web Search Indexing API*, *PageSpeed Insights API*.
3. Configure the OAuth consent screen (External, add yourself as a test user).
4. Create an OAuth client of type **Desktop app** and download its JSON file.
5. Merchant API only: [register your Cloud project](https://developers.google.com/merchant/api/guides/quickstart) with your Merchant Center account.
6. Optional: create an API key restricted to PageSpeed Insights (the anonymous quota is shared and often exhausted).

### 2. Install and authorize

```bash
# with uv (recommended): nothing to install, uvx fetches the package from PyPI
uvx google-ecommerce-mcp setup --client-secret path/to/client_secret.json --with-merchant
# read-only scopes only by default; --with-merchant / --with-indexing add the write-capable ones you need

# or with pip
pip install google-ecommerce-mcp
google-ecommerce-mcp setup --client-secret path/to/client_secret.json
```

Latest development version: `uvx --from git+https://github.com/MoonEyes/google-ecommerce-mcp google-ecommerce-mcp`.

Your browser opens the Google consent screen. The token is then stored in your OS keyring. Check everything with `google-ecommerce-mcp check`.

### 3. Add it to your MCP client

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "google-ecommerce": {
      "command": "uvx",
      "args": ["google-ecommerce-mcp"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GSC_SITE_URL": "sc-domain:example.com",
        "MERCHANT_ACCOUNT_ID": "1234567890",
        "GTM_CONTAINER_ID": "GTM-XXXXXXX",
        "PAGESPEED_API_KEY": ""
      }
    }
  }
}
```

**Claude Code**:

```bash
claude mcp add google-ecommerce -e GA4_PROPERTY_ID=123456789 -e GSC_SITE_URL=sc-domain:example.com \
  -e MERCHANT_ACCOUNT_ID=1234567890 -e GTM_CONTAINER_ID=GTM-XXXXXXX \
  -- uvx google-ecommerce-mcp
```

Every variable is optional: a tool for a service you did not configure simply answers `not_configured`.

| Variable | Example | Used by |
|---|---|---|
| `GA4_PROPERTY_ID` | `123456789` (numeric property id) | GA4 tools |
| `GSC_SITE_URL` | `sc-domain:example.com` or `https://www.example.com/` | Search Console tools |
| `MERCHANT_ACCOUNT_ID` | `1234567890` | Merchant tools |
| `GTM_CONTAINER_ID` | `GTM-XXXXXXX` | `gtm_inventory` |
| `PAGESPEED_API_KEY` | API key | `pagespeed` |
| `GOOGLE_TOKEN_FILE` | `~/.config/google-ecommerce-mcp/token.json` | store the token in a file instead of the keyring |

## How a call works

![Sequence of one tool call](https://raw.githubusercontent.com/MoonEyes/google-ecommerce-mcp/main/docs/diagrams/sequence-tool-call.png)

## Security notes

Details: [docs/SECURITY.md](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/docs/SECURITY.md).

- Read-only is enforced, not just declared: every request is checked against an allow-list before it is sent, and CI fails if any tool tries an endpoint outside it. `readOnlyHint` is only a hint.
- `setup` requests read-only scopes only. Google has no read-only scope for **Merchant Center** (`content`) or the **Indexing API** (`indexing`); they are requested only with `--with-merchant` / `--with-indexing`, and `server_status` flags them when present.
- Every result carries `fetched_at` and `freshness`; report tools return the `date_range` queried, resolved in the data's timezone, with `data_complete`.
- Revoke access at any time from your [Google account permissions](https://myaccount.google.com/permissions).

## Limitations

- The Merchant API is recent and Google keeps changing it; the older Content API for Shopping is being shut down. Open an issue if a call breaks.
- One site, Merchant account and container per server instance; GA4 tools accept any readable `property_id`. Run several instances for several shops.
- GA4 Data API quotas apply to `ga4_report`.

## Contributing

See [CONTRIBUTING.md](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/CONTRIBUTING.md). Security reports: [SECURITY.md](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/SECURITY.md).

## Development

```bash
pip install -e ".[dev]"
pytest
```

Tests run offline with a fake HTTP session; no Google account needed.

## License

MIT, see [LICENSE](https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/LICENSE).