English · Español

ga4-seo-mcp — site measurement for AI agents, end to end

Get a site's measurement ready end to end: GA4 + Search Console + PageSpeed, with optional, guarded writes. An open source Model Context Protocol server for Google Analytics 4 & Search Console. Most MCP servers for Google read your data; this one can also set it up: property, web stream, key events, custom dimensions, Search Console DNS verification, sitemap and a PageSpeed baseline — read-only until you say otherwise.

Tags: mcp-server · ga4 · google-analytics · search-console · seo · pagespeed · core-web-vitals · keyword-research · claude-code · cursor

_{Real run: psi_audit on a public site and bootstrap_site_measurement(apply=False) planning a new site. The demo script redacts the account ID.}

💡 Why this one?

Launching a site means the same chores every time: create the GA4 property and its web stream, mark the key events, register custom dimensions, add the domain to Search Console, publish a DNS TXT record, verify it, submit the sitemap, and record a PageSpeed baseline. ga4-seo-mcp turns that into one plan your agent shows you, and one confirmation.

_{Based on each project's README on 2026-10-19; "—" means we did not find it documented. Corrections welcome. Those projects go wider than this one (Bing, AdSense, WordPress, GEO audits…); this one goes deeper on setting up measurement.}

🤝 Need this done for you?

This server is built and maintained by Germani Uicab. If you'd rather not run it yourself, ServerStack Solutions can get your GA4 + Search Console measurement ready: a written plan, property and key events configured, the DNS verification and sitemap in place, and a PageSpeed baseline — with a QA pass before handover.

Extras: optional keyword research with DataForSEO (exact long-tail volumes) and Google Ads Keyword Planner (free, bucketed volumes), with es-MX defaults that you can override.

⚡ Quick start

1. Install uv — the client launches the server with uvx; nothing else to install.

2. Log in with the minimum scopes. The CLI prints the exact gcloud command for the toolsets you enable:

uvx ga4-seo-mcp auth-command --client-id-file=oauth-client.json
# gcloud auth application-default login --client-id-file=oauth-client.json --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/webmasters.readonly

Run the printed command. Google blocks Analytics and Search Console scopes on gcloud's built-in OAuth client, so you need your own (a one-time, few-minute setup) or a service account — both are explained in docs/AUTH.md.

3. Check everything before connecting a client (read-only, changes nothing):

uvx ga4-seo-mcp doctor
# [ok] credentials found: Credentials via Application Default Credentials
# [ok] access token refreshed
# [ok] token has the 2 scope(s) these toolsets need
# [ok] admin: <n> account(s) visible on the first page
# [ok] data: responded (<n> metrics in the schema)
# [ok] gsc: <n> site(s) visible
# [ok] psi: no Google login needed; PAGESPEED_API_KEY set
# all checks passed

4. Add it to your client (Claude Code shown; others below):

claude mcp add ga4-seo -- uvx ga4-seo-mcp

Ask: "List my GA4 properties and show last week's sessions for the first one."

Before the first PyPI release, run it from GitHub instead: uvx --from git+https://github.com/GermaniU/ga4-seo-mcp ga4-seo-mcp.

🧰 Toolsets, scopes and tools

Enable only what you need with --toolsets (or GA4SEO_TOOLSETS). Default: admin,data,gsc,psi. Only the tools of active toolsets are registered, and the OAuth scopes follow.

Tool counts from the real registry: 24 with the defaults, 37 with --enable-writes, 8 with --toolsets data, 41 with every toolset and writes. The full list with descriptions is in docs/TOOLS.md (generated from the registry and checked in CI).

Prompts: audit_ga4_setup, seo_360_audit, portfolio_performance_digest and launch_site_measurement (the guided flow: plan → your confirmation → apply → DNS verification → sitemap → PageSpeed baseline).

bootstrap_site_measurement

bootstrap_site_measurement(site_url="https://example.com", account_id="123456789",
                           property_display_name="Example", time_zone="America/Mexico_City",
                           currency_code="USD", key_events=["generate_lead"],
                           custom_dimensions=[{"parameter_name": "plan_type", "display_name": "Plan type"}])

• apply=False (default): a plan. Read-only and always registered. It finds the existing property and web stream by the site's domain, the key events and custom dimensions already declared, and the Search Console domain property, and lists what would be created.
• apply=True: executes the plan. Only works when the server runs with --enable-writes; otherwise it fails before touching anything. Idempotent: it skips what exists, so you can re-run it. Returns a step-by-step report with the measurement ID (G-…) and the DNS TXT token.
• DNS verification (sc_verify_site_dns) and the sitemap (sc_submit_sitemap) stay explicit follow-up steps: you have to publish the TXT record first.

🔒 Security model

Defaults are safe for a single user on a laptop. Details and threat model: SECURITY.md.

• Read-only by default. Without --enable-writes (or GA4SEO_ENABLE_WRITES=1), tools that create, update, delete, submit or verify are not registered at all — the model cannot call what does not exist.
• MCP annotations on every tool: readOnlyHint on reads, destructiveHint on deletes and updates, idempotentHint where repeating is harmless, openWorldHint everywhere. Clients that honor them can auto-approve reads and ask before writes.
• Minimum scopes: each Google client requests only the scope of the call it makes; auth-command asks only for the scopes of your toolsets.
• HTTP transport (--transport streamable-http): binds to 127.0.0.1, DNS-rebinding protection on, CORS off unless MCP_CORS_ORIGINS, and an optional bearer token MCP_AUTH_TOKEN (401 without it). Listening on 0.0.0.0 without a token prints a warning.
• Secrets (DataForSEO, Ads developer token, PageSpeed key) come only from environment variables or a chmod 600 file, and are never logged or returned in errors.

⚙️ Configuration

Copy .env.example as a starting point.

🔌 Connect your client

Every client launches the server over stdio. Add --enable-writes to args only for the session where you actually want to set up a site.

Claude Code

claude mcp add ga4-seo -- uvx ga4-seo-mcp
# with options:
claude mcp add ga4-seo -e PAGESPEED_API_KEY=your-key -- uvx ga4-seo-mcp --toolsets admin,data,gsc,psi

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "ga4-seo": {
      "command": "uvx",
      "args": ["ga4-seo-mcp"],
      "env": { "PAGESPEED_API_KEY": "your-key" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "ga4-seo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ga4-seo-mcp"]
    }
  }
}

Docker (stdio). Mount your credentials file read-only — the ADC file from gcloud or a service account key — and run as your own user so the container can read a 0600 file:

docker run -i --rm --user "$(id -u):$(id -g)" \
  -v ~/.config/gcloud/application_default_credentials.json:/creds/credentials.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/creds/credentials.json \
  ghcr.io/germaniu/ga4-seo-mcp

HTTP (several clients sharing one server):

MCP_AUTH_TOKEN=$(openssl rand -hex 32) uvx ga4-seo-mcp --transport streamable-http
# endpoint: http://127.0.0.1:8000/mcp  (send Authorization: Bearer <token>)

🩹 Troubleshooting

📚 Documentation

• docs/AUTH.md — own OAuth client vs service account, scopes per toolset, Test Users.
• docs/TOOLS.md — every tool and prompt, generated from the registry.
• docs/ARCHITECTURE.md — modules, registration and security layers.
• SECURITY.md · CONTRIBUTING.md · CHANGELOG.md

🧪 Development

uv sync --all-extras
uv run ruff check . && uv run ruff format --check . && uv run pytest
uv run python scripts/smoke_stdio.py --expect 24   # real stdio initialize + tools/list

📄 License

MIT. Not affiliated with or endorsed by Google. Google Analytics, Search Console and PageSpeed Insights are trademarks of Google LLC.