ai-google-analytics-mcp

MCP server to provision Google Analytics 4 for local AI/web projects: create properties and web data streams, capture measurement IDs, inject gtag into HTML, and write .ga4.config.json in project roots.

For reporting and monitoring, use Google's official read-only analytics-mcp alongside this server (see CONTEXT.md).

Tools

Tool	Purpose
`get_ga4_auth_setup_instructions`	gcloud ADC + API enablement steps
`list_ga_account_summaries`	Discover accounts/properties (readonly Admin API)
`provision_ga4_property`	Create GA4 property under an account
`create_web_data_stream`	Create web stream → `G-XXXXXXXX`
`render_ga4_gtag_snippet`	HTML snippet for a measurement ID
`inject_ga4_gtag_into_file`	Patch a local HTML/layout file
`render_ga4_nextjs_component`	Next.js `GoogleAnalytics.tsx` source (env or inline id)
`scaffold_ga4_nextjs_tracking`	Write component, wire `layout.tsx`, set `.env.local`
`save_project_ga4_config`	Write `.ga4.config.json` in a project dir
`provision_project_ga4_setup`	Property + stream + optional config/inject (+ optional `registry_slug`, `tracking_mode`)
`scan_local_ga4_configs`	Filesystem inventory of `.ga4.config.json` under scan roots
`list_projects_needing_ga4`	Registry projects missing GA4 config/metadata
`detect_project_tracking_stack`	Recommend html vs nextjs wiring for a repo
`get_analytics_monitoring_companion_guide`	Pair with official read-only `analytics-mcp`
`get_ga4_integration_status`	Whether launcher/keymaster hooks are configured
`list_registry_projects_for_ga4`	Registry projects + `.ga4.config.json` / `.keymaster` hints
`resolve_project_for_ga4`	Slug and/or path → website_url, web roots, agent hints
`sync_ga4_to_launcher_registry`	Write `analytics.ga4` on registry row (opt-in write)

Optional: launcher registry & keymaster

Public-repo safe: no hardcoded paths, no imports from sibling repos. Set env on your MCP host only if you use these services:

GA4_LAUNCHER_REGISTRY_JSON — read launcher registry.json (same format as launcher-project-registry)
GA4_LAUNCHER_REGISTRY_WRITABLE=true — allow sync_ga4_to_launcher_registry / registry_slug on provision
GA4_KEYMASTER_DATABASE or GA4_KEYMASTER_HINTS=true — status hints only; secrets stay in keymaster MCP (keymaster_register_key for GA service accounts). Measurement IDs remain in .ga4.config.json.

See docs/adr/0003-optional-registry-keymaster-hooks.md.

Quick start

cd /path/to/ai-google-analytics-mcp
uv sync
uv run pytest -q
uv run ga4-provision-mcp

Authentication

Full walkthrough: Google Analytics GA4 Service Account Setup Guide — GCP project, enable Admin (and optional Data) API, create a service account, grant GA account access, and point GOOGLE_APPLICATION_CREDENTIALS at the JSON key.

If gcloud auth application-default login shows "This app is blocked", use a service account (recommended): see also research/notes/gcloud-this-app-is-blocked.md.

# After SA JSON is on disk and SA email has Editor on your GA account:
export GOOGLE_APPLICATION_CREDENTIALS=~/.config/ga4/ga4-provisioner-sa.json

Copy .env.example → .env and set GOOGLE_APPLICATION_CREDENTIALS + optional GA4_DEFAULT_ACCOUNT_ID.

Hermes / MCP config (stdio)

# ~/.hermes/config.yaml (example)
mcp_servers:
  ga4_provision:
    command: uv
    args:
      - run
      - --directory
      - /path/to/ai-google-analytics-mcp
      - ga4-provision-mcp

Companion (read-only reports):

  google_analytics:
    command: pipx
    args: ["run", "analytics-mcp"]
    env:
      CLOUDSDK_CORE_PROJECT: your-gcp-project-id

Agent workflow example

"Provision GA4 for this repo: production URL https://my-app.example, inject into public/index.html, save config in project root."

The agent calls provision_project_ga4_setup with project_dir and inject_html_path.

Docs

SECURITY.md — transport (stdio), trust model, credentials, safe deployment
google-analytics-ga4-service-account-setup-guide.md — step-by-step Google Cloud + GA4 + service account setup
CONTEXT.md — rules and architecture
HERMES.md — agent smoke + guardrails
docs/adr/ — durable decisions
research/ — external references (official analytics-mcp, etc.)
BRIEF.md — original Gemini conversation blueprint