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 your data; this one can also : property, web stream, key events, custom dimensions, Search Console DNS verification, sitemap and a PageSpeed baseline — read-only until you say otherwise.
Set up and audit site measurement: GA4, Search Console and PageSpeed. Read-only unless enabled.
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 0.13.4 or newer — 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:
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."
🧰 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.
GA4 Data API: reports, realtime, top pages, events, traffic sources, portfolio
analytics.readonly
—
8 + 0
gsc
Search Console: queries, pages, sitemaps, domain add + DNS verification
webmasters.readonly
webmasters, siteverification
5 + 3
psi
PageSpeed Insights: Lighthouse lab + CrUX field data
none (PAGESPEED_API_KEY recommended)
—
2 + 0
dataforseo
DataForSEO keyword ideas and exact volumes (paid)
none (DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD)
—
2 + 0
ads
Google Ads Keyword Planner (needs pip install 'ga4-seo-mcp[ads]')
adwords
—
2 + 0
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).
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, and LAN clients need MCP_ALLOWED_HOSTS or the rebinding protection answers 421.
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
Variable
Default
Description
GOOGLE_APPLICATION_CREDENTIALS
—
Service account key file. Unset = Application Default Credentials from gcloud.
GA4SEO_TOOLSETS
admin,data,gsc,psi
Same as --toolsets.
GA4SEO_ENABLE_WRITES
0
1 = same as --enable-writes.
PAGESPEED_API_KEY
—
Recommended: the anonymous PageSpeed quota is shared and often exhausted (429).
DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD
—
dataforseo toolset.
GOOGLE_ADS_DEVELOPER_TOKEN
—
ads toolset, or ~/.config/ga4-seo-mcp/dev-token with chmod 600.
GOOGLE_ADS_LOGIN_CUSTOMER_ID
—
Only when operating through a manager (MCC) account.
MCP_TRANSPORT
stdio
stdio, streamable-http or sse.
MCP_HOST / MCP_PORT
127.0.0.1 / 8000
HTTP bind address and port. A specific non-loopback address is added to the allowed Host headers; 0.0.0.0 is not, so set MCP_ALLOWED_HOSTS for LAN clients.
MCP_AUTH_TOKEN
—
Require Authorization: Bearer <token> on every HTTP request.
MCP_CORS_ORIGINS
—
Comma-separated exact origins for a browser client. Never *.
MCP_ALLOWED_HOSTS
—
Comma-separated host/IP values clients use (e.g. 192.168.1.10). Required when binding 0.0.0.0 and connecting over the LAN; DNS-rebinding protection rejects everything else with 421.
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:
This app is blocked / access_denied during gcloud ... login
gcloud's built-in client cannot request Analytics or Search Console scopes. Use your own OAuth client (--client-id-file) and add yourself as a Test User of its consent screen — docs/AUTH.md.
cloud-platform scope is required but not requested
Use the command printed by ga4-seo-mcp auth-command: gcloud needs cloud-platform in the list. The server itself never requests it.
403 ... API has not been used in project
Enable the Google Analytics Admin API, Google Analytics Data API and Search Console API in your quota project, then gcloud auth application-default set-quota-project my-gcp-project.
403 ... does not have sufficient permissions for this property
Add your user (or the service account email) to the GA4 property or Search Console site.
ga4-seo-mcp doctor says the token is missing scopes
You logged in before enabling a toolset or writes. Re-run the auth-command output.
Write tools do not show up
Start the server with --enable-writes. It is off by default on purpose.
PageSpeed Insights error 429
The anonymous quota is shared by everyone. Create an API key and set PAGESPEED_API_KEY.