google-ecommerce-mcp 0.1.0__tar.gz

google_ecommerce_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+token*.json
+client_secret*.json
+.env

google_ecommerce_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-10-04)
+
+First public release.
+
+- 12 read-only tools: GA4 (report, realtime), Search Console (performance, URL inspection, sitemaps),
+  Merchant Center (data sources, product issues with pagination, MCQL reports), Tag Manager inventory,
+  Indexing API status, PageSpeed Insights.
+- `setup` command (OAuth consent in the browser) and `check` command.
+- `install` command and one-line installers (`install.ps1`, `install.sh`): install uv if needed, ask the ids,
+  authorize, register the server in Claude Desktop with a timestamped backup. Handles UTF-8 BOM configs,
+  refuses to overwrite an existing entry without `--force`, never touches an unparsable config.
+- OAuth token stored in the OS keyring by default, or in a file with `GOOGLE_TOKEN_FILE`.
+- Offline test suite, including a guard that every outgoing call is read-only.
+- Documentation: architecture, tool reference, Google Cloud setup, security model, troubleshooting,
+  example prompts and client configs, Archify diagrams (architecture, tool call, setup), CI on 3 OSes.
+- Release pipeline: PyPI trusted publishing and the official MCP Registry (`io.github.MoonEyes/google-ecommerce-mcp`).

google_ecommerce_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Thanks for helping. Issues and pull requests are welcome, in English or French.
+
+## Ground rules
+
+1. **Read-only stays read-only.** A tool must never call an endpoint that creates, updates, publishes, submits or deletes. If a new tool needs a query `POST`, add its URL suffix to `allowed_posts` in `tests/test_server.py::test_every_call_is_read_only` and explain why in the PR.
+2. **Errors are results.** Use `_call` and `@_guard` so failures come back as `{"error": ...}` objects.
+3. **No hard-coded accounts.** Every id comes from an environment variable read in `config.py`.
+4. **Keep answers small.** Flatten Google responses to what a model needs and cap row counts.
+
+## Development
+
+```bash
+git clone https://github.com/MoonEyes/google-ecommerce-mcp
+cd google-ecommerce-mcp
+python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run offline against a fake HTTP session; no Google account is needed. Every new tool needs at least one test, and `test_tools_are_registered_with_real_signatures` must be updated with the new tool count.
+
+To try a change against real data, run `google-ecommerce-mcp setup` with your own OAuth client, then:
+
+```bash
+npx @modelcontextprotocol/inspector google-ecommerce-mcp
+```
+
+## Adding a tool
+
+1. Write the function in `server.py` under the right section, decorated with `@mcp.tool()` then `@_guard`.
+2. Its docstring is what the model reads: say what it answers, the parameter formats and one example value.
+3. Document it in `docs/TOOLS.md` and the table in `README.md`.
+4. Add a line to `CHANGELOG.md`.
+
+## Diagrams
+
+Diagram sources are JSON files in `docs/diagrams/`, rendered with Archify (see `docs/ARCHITECTURE.md`). Update the JSON, rerender, and commit both the JSON, the HTML and the PNG.
+
+## Releasing (maintainers)
+
+1. Bump the version in `pyproject.toml`, `server.json` (`version` and `packages[0].version`) and `src/google_ecommerce_mcp/__init__.py`, and add a `CHANGELOG.md` entry.
+2. Commit, then `git tag vX.Y.Z && git push origin vX.Y.Z`.
+3. `.github/workflows/release.yml` checks the versions match, runs the tests, publishes to PyPI (trusted publishing) and to the official MCP Registry (GitHub OIDC). No token is stored anywhere.
+4. Create the GitHub release from the tag with the changelog entry as notes.

google_ecommerce_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MoonEyes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

google_ecommerce_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: google-ecommerce-mcp
+Version: 0.1.0
+Summary: Read-only MCP server giving AI assistants one door to the Google services an online shop lives on: GA4, Search Console, Merchant Center, Tag Manager, Indexing API and PageSpeed.
+Project-URL: Homepage, https://github.com/MoonEyes/google-ecommerce-mcp
+Project-URL: Issues, https://github.com/MoonEyes/google-ecommerce-mcp/issues
+Project-URL: Documentation, https://github.com/MoonEyes/google-ecommerce-mcp/tree/main/docs
+Project-URL: Changelog, https://github.com/MoonEyes/google-ecommerce-mcp/blob/main/CHANGELOG.md
+Author-email: MoonEyes <contact@mooneyeswargame.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,ecommerce,ga4,google-analytics,google-tag-manager,mcp,merchant-center,model-context-protocol,search-console,seo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.10
+Requires-Dist: google-auth-oauthlib>=1.0
+Requires-Dist: google-auth>=2.20
+Requires-Dist: keyring>=24
+Requires-Dist: mcp<2,>=1.2
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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)
+
+![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).
+- **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 |
+| `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 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, straight from GitHub (recommended)
+uvx --from git+https://github.com/MoonEyes/google-ecommerce-mcp google-ecommerce-mcp setup --client-secret path/to/client_secret.json
+
+# or with pip
+pip install git+https://github.com/MoonEyes/google-ecommerce-mcp
+google-ecommerce-mcp setup --client-secret path/to/client_secret.json
+```
+
+A PyPI release (`uvx google-ecommerce-mcp`) will follow; until then, install from GitHub as above.
+
+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": ["--from", "git+https://github.com/MoonEyes/google-ecommerce-mcp", "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 --from git+https://github.com/MoonEyes/google-ecommerce-mcp 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).
+
+- The server never calls a write endpoint (no Tag Manager publish, no feed upload, no sitemap submission). `tests/test_server.py::test_every_call_is_read_only` checks every outgoing call.
+- Scopes are read-only except **Merchant Center** (`content`) and **Indexing API** (`indexing`): Google has no read-only scope for these. The server does not use them to write, but treat the token as sensitive, or remove those scopes if you do not need the services.
+- 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 property, site, Merchant account and container per server instance. 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).

google_ecommerce_mcp-0.1.0/README.md

@@ -0,0 +1,175 @@
+# 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)
+
+![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).
+- **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 |
+| `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 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, straight from GitHub (recommended)
+uvx --from git+https://github.com/MoonEyes/google-ecommerce-mcp google-ecommerce-mcp setup --client-secret path/to/client_secret.json
+
+# or with pip
+pip install git+https://github.com/MoonEyes/google-ecommerce-mcp
+google-ecommerce-mcp setup --client-secret path/to/client_secret.json
+```
+
+A PyPI release (`uvx google-ecommerce-mcp`) will follow; until then, install from GitHub as above.
+
+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": ["--from", "git+https://github.com/MoonEyes/google-ecommerce-mcp", "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 --from git+https://github.com/MoonEyes/google-ecommerce-mcp 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).
+
+- The server never calls a write endpoint (no Tag Manager publish, no feed upload, no sitemap submission). `tests/test_server.py::test_every_call_is_read_only` checks every outgoing call.
+- Scopes are read-only except **Merchant Center** (`content`) and **Indexing API** (`indexing`): Google has no read-only scope for these. The server does not use them to write, but treat the token as sensitive, or remove those scopes if you do not need the services.
+- 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 property, site, Merchant account and container per server instance. 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).

google_ecommerce_mcp-0.1.0/SECURITY.md

@@ -0,0 +1,13 @@
+# Security policy
+
+## Supported versions
+
+Only the latest release receives fixes.
+
+## Reporting a vulnerability
+
+Please do not open a public issue. Use GitHub's **Report a vulnerability** button (Security tab of this repository) or write to contact@mooneyeswargame.com. Expect an answer within 7 days.
+
+Never include a real OAuth token, client secret or account data in a report.
+
+The threat model, scopes and token storage are described in [docs/SECURITY.md](docs/SECURITY.md).

google_ecommerce_mcp-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,61 @@
+# Architecture
+
+google-ecommerce-mcp is a small, local, read-only bridge between an MCP client (Claude Desktop, Claude Code, or any other MCP host) and six Google APIs.
+
+![Architecture overview](diagrams/architecture-overview.png)
+
+Interactive version: [`diagrams/architecture-overview.html`](diagrams/architecture-overview.html) (open it locally in a browser; it is self-contained).
+
+## Components
+
+| Component | File | Role |
+|---|---|---|
+| Entry point | `src/google_ecommerce_mcp/__main__.py` | `setup`, `check`, or (default) run the MCP server over stdio |
+| Configuration | `config.py` | Reads account ids from environment variables, defines the OAuth scopes |
+| Credentials | `auth.py` | Stores the refresh token in the OS keyring (or a file), refreshes access tokens in memory |
+| Installer | `installer.py` | `install` command: prompts, OAuth setup, Claude Desktop config merge with backup |
+| Tools | `server.py` | 12 FastMCP tools, one HTTP session, every call wrapped so errors come back as data |
+
+There is no database, no cache on disk, no background job and no network listener.
+
+## Transport
+
+The MCP client launches the server as a child process and talks to it over **stdio** (JSON-RPC on stdin/stdout). Nothing listens on a port, so nothing on your network can reach the server. The process lives as long as the client keeps it open.
+
+## A tool call, step by step
+
+![Sequence of one tool call](diagrams/sequence-tool-call.png)
+
+1. You ask a question in the chat. The model picks a tool, for example `ga4_report`, and the client sends `tools/call`.
+2. On the first call only, the server reads the refresh token from the OS keyring.
+3. If the in-memory access token is missing or expired, `google-auth` refreshes it against Google's token endpoint. Access tokens live about one hour and are never written to disk.
+4. The server calls the Google API with `Authorization: Bearer ...`.
+5. The raw response is flattened into compact JSON (for example GA4 rows become `{"dimension": value, "metric": value}` objects) and returned to the client.
+
+## One-time setup
+
+![Sequence of the setup command](diagrams/sequence-setup.png)
+
+`google-ecommerce-mcp setup --client-secret client_secret.json` runs Google's installed-app OAuth flow: a temporary localhost redirect catches the authorization code, the code is exchanged for a refresh token, and the token is stored. The setup command is the only code path that writes the token.
+
+## Design choices
+
+**Read-only by construction.** The server only issues `GET` requests and the `POST` requests Google uses for queries (`:runReport`, `:runRealtimeReport`, `searchAnalytics/query`, `index:inspect`, `reports:search`). `tests/test_server.py::test_every_call_is_read_only` calls every tool against a fake HTTP session and fails if any other method or URL appears.
+
+**Errors are results, not exceptions.** A missing variable returns `{"error": "not_configured", ...}`, an HTTP error returns `{"error": <status>, "detail": ...}`, a network failure returns `{"error": "network", ...}`. The model can read and explain the problem instead of seeing a crashed tool.
+
+**Configuration per service.** Every environment variable is optional. Configure only what you use; the other tools answer `not_configured`.
+
+**Plain HTTP instead of Google client libraries.** The REST endpoints are called with `requests`. That keeps the install small (no `google-api-python-client` discovery documents) and makes each call visible in the source.
+
+**Result caps.** Row-returning tools cap `limit` at 1,000 to keep answers within a model's context window. Merchant product scanning is paginated (250 per page, `max_pages` bound).
+
+## Diagram sources
+
+The diagrams are generated with Archify (MIT-licensed diagram renderer) from the JSON specifications next to them in [`docs/diagrams/`](diagrams/). Each one passed Archify's validate, deliver, check and browser-check gates at showcase quality. To change a diagram, edit the JSON and run:
+
+```bash
+archify finalize architecture docs/diagrams/architecture-overview.json docs/diagrams/architecture-overview.html --quality showcase
+archify finalize sequence docs/diagrams/sequence-tool-call.json docs/diagrams/sequence-tool-call.html --quality showcase
+archify finalize sequence docs/diagrams/sequence-setup.json docs/diagrams/sequence-setup.html --quality showcase
+```

google_ecommerce_mcp-0.1.0/docs/SECURITY.md

@@ -0,0 +1,53 @@
+# Security model
+
+This page explains what the server can access, what it does with it, and how to limit the damage if something goes wrong. To report a vulnerability, see [SECURITY.md](../SECURITY.md) at the repository root.
+
+## What is protected
+
+The asset is the **OAuth refresh token**. Whoever holds it, together with your OAuth client, can call the granted Google APIs as you until you revoke it.
+
+## Where the token lives
+
+| Storage | When | Protection |
+|---|---|---|
+| OS keyring (default) | Always, unless `GOOGLE_TOKEN_FILE` is set | Windows Credential Manager, macOS Keychain, Secret Service: encrypted at rest, scoped to your OS user |
+| File | `GOOGLE_TOKEN_FILE` set | Written with permissions `0600` on POSIX systems; on Windows rely on your profile ACLs |
+
+Access tokens (valid about one hour) stay in process memory and are never written. The refresh token is written only by the `setup` command.
+
+## Scopes and what they could do
+
+| Scope | Read-only? | Used for | What the token could do if stolen |
+|---|---|---|---|
+| `analytics.readonly` | yes | GA4 reports | Read analytics data |
+| `webmasters.readonly` | yes | Search Console | Read search data and inspect URLs |
+| `tagmanager.readonly` | yes | GTM inventory | Read container configuration |
+| `content` | **no** | Merchant API | Read **and modify** Merchant Center products, feeds and settings |
+| `indexing` | **no** | Indexing status | Read notification metadata **and submit** URL notifications |
+
+Google offers no read-only scope for the Merchant API or the Indexing API. The server never calls their write endpoints, but the token itself carries the permission. Treat it like a password.
+
+**Reduce the scopes** if you do not need a service: edit `SCOPES` in `src/google_ecommerce_mcp/config.py` (for example remove `content` if you do not use Merchant Center) and rerun `setup`.
+
+## Guarantees enforced by code
+
+- Only `GET` and query `POST`s are sent. `tests/test_server.py::test_every_call_is_read_only` runs every tool against a recording fake session and fails on any other method or on URLs containing `:publish`, `:create_version`, `fetchNow` or `/delete`.
+- No listener: stdio transport only, no open port.
+- No telemetry, no third-party endpoint: the only hosts contacted are `*.googleapis.com` and Google's OAuth endpoint.
+- No account id is hard-coded; everything comes from your environment.
+
+## Threats and mitigations
+
+| Threat | Mitigation |
+|---|---|
+| Malware running as your OS user reads the keyring | Out of scope for any local tool; revoke the token if your machine is compromised |
+| Token file committed to git | Use the keyring (default). `.gitignore` excludes `token*.json` and `client_secret*.json` |
+| Prompt injection makes the model call tools with odd arguments | Tools cannot write, so the worst case is reading your own data into the conversation. Review what you paste into the chat |
+| Data leaves your machine through the model | Tool results go to your MCP client and therefore to the model provider you use. Do not connect accounts whose data you may not share with that provider |
+| Supply-chain change in a dependency | Dependencies are few and pinned by range (`mcp<2`); install from a tagged release and review updates |
+
+## Revoke access
+
+- One click: [Google account > Security > Third-party connections](https://myaccount.google.com/permissions), remove your app.
+- Or delete the OAuth client in Google Cloud Console: every token issued to it stops working.
+- Then delete the local copy: `keyring del google-ecommerce-mcp oauth-token`, or delete the token file.