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