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, a small French shop selling 3D-printed tabletop terrain, because no existing MCP server covered GA4, Search Console and Merchant Center together.

Documentation

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

Quick install

Create your Google OAuth client first (step 1 below), then run one line. The installer installs 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):

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

macOS / Linux:

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. Short version:

1. In Google Cloud Console, 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 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

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

{
  "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:

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.

How a call works

Security notes

Details: 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.

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. Security reports: SECURITY.md.

Development

pip install -e ".[dev]"
pytest

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

License

MIT, see LICENSE.