Open source · MIT · Node.js 22+ · Docker
MCP server for Google Search Console and Google Analytics 4
39 tools for AI agents: Search Console performance, indexing checks, GA4 reports and site verification. Runs as a Docker image, MIT.
What it does
- Search Console: properties, sitemaps and search analytics with period-over-period comparison.
- Opportunities: quick wins, declining content, CTR gaps, content gaps and topic clusters by query intent.
- Indexing: URL Inspection for one URL or up to 50 per call, plus an indexing audit of top traffic pages.
- GA4: list and create properties and web data streams, run reports and realtime reports, read metadata.
- Site verification: get a FILE, DNS_TXT, META or ANALYTICS token and complete ownership verification.
- Weekly SEO report and an A–F health check; responses come with a Summary, Data, Recommendations and Limitations.
What it does
The server exposes 39 tools built on five Google APIs:
| API | Used for |
|---|---|
Search Console API (webmasters v3) | Properties, sitemaps, search analytics |
Search Console API (searchconsole v1) | URL Inspection |
| Google Analytics Admin API (v1beta) | GA4 accounts, properties, data streams |
| Google Analytics Data API (v1beta) | GA4 reports, realtime, metadata |
| Site Verification API (v1) | Verification tokens, ownership verification |
Beyond raw API access, tool responses are post-processed by a local analysis layer:
position-based CTR benchmarks, trend detection, query intent classification,
opportunity scoring, and a recommendation engine. Most tools return a readable
Summary and Data block rather than bare JSON, plus Recommendations and
Limitations sections when there is something worth saying.
Infrastructure: an in-memory TTL+LRU cache (search analytics 15 min when the range ends within the last 2 days and 1 h once it is older, sitemaps 15 min, site lists 30 min, URL inspections 1 h), a rate limiter (20 req/s, burst 30), and two transports — stdio (default) and stateless Streamable HTTP.
Setup
1. Get Google credentials
Enable these APIs in your Google Cloud project: Search Console API, Google Analytics Admin API, Google Analytics Data API, and Site Verification API.
The server requests these OAuth scopes:
https://www.googleapis.com/auth/webmasters
https://www.googleapis.com/auth/analytics.readonly
https://www.googleapis.com/auth/analytics.edit
https://www.googleapis.com/auth/siteverification.verify_only
Option A — Service account (best for servers and automation):
- Google Cloud Console → IAM & Admin → Service Accounts → create one.
- Add a key → Create new key → JSON → download it.
- In Search Console → Settings → Users and permissions → add the service account's email address.
- In GA4 → Admin → Property access management → add the same email.
Option B — OAuth 2.0 (best for personal, local use):
- Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app.
- Download the client secrets JSON.
- On first run, the server prints an authorization URL to stderr and starts a temporary local callback listener. Open the URL, consent, done.
- The token is stored at
~/.google-webtools-mcp/token.jsonand refreshed automatically, so you authorize only once.
2. Environment variables
| Variable | Purpose |
|---|---|
GOOGLE_APPLICATION_CREDENTIALS | Path to a service account JSON key file. |
GOOGLE_SERVICE_ACCOUNT_KEY | The service account key as an inline JSON string — for Docker and CI, where mounting a file is awkward. |
GSC_OAUTH_CLIENT_SECRETS_FILE | Path to an OAuth client secrets JSON file. |
PORT | HTTP transport port. Default 3000. Only read with --http. |
Authentication methods are tried in this order, and the first one that yields
usable credentials wins. A method that fails is recorded and the next one is
tried: if GOOGLE_APPLICATION_CREDENTIALS points at a missing or malformed
file, the server does not stop there — with OAuth configured (and a saved token)
it starts under the OAuth account instead. Check the [auth] Authenticated via …
line on stderr to see which identity was actually used.
- Service account —
GOOGLE_APPLICATION_CREDENTIALS, thenGOOGLE_SERVICE_ACCOUNT_KEY, then./credentials.jsonif itstypeisservice_account. - Application Default Credentials (
gcloud auth application-default login) — skipped ifGOOGLE_APPLICATION_CREDENTIALSis set. - OAuth via
GSC_OAUTH_CLIENT_SECRETS_FILE. ./credentials.jsonin the working directory, if it looks like OAuth client secrets (has aninstalledorwebkey).
If none succeed, the server prints a setup guide to stderr and starts anyway, so a host or a directory can still list its tools without keys. Every tool call then looks for credentials again and, until one method works, returns the same error with the setup hint instead of calling Google. Fixing the key file needs no restart.
3. Install
docker run -i --rm \
-v /absolute/path/to/service-account.json:/creds/sa.json:ro \
-e GOOGLE_APPLICATION_CREDENTIALS=/creds/sa.json \
ghcr.io/stufently/google-webtools-mcp:1.2.2
Replace /absolute/path/to/service-account.json with the key file from step 1 (Docker needs an absolute path), then paste the command. Docker pulls the image on the first run (amd64 and arm64), so nothing else needs installing. It should print Server running on stdio to stderr and wait for a client (Ctrl+C to quit). Every client block below runs this same docker run; the key file is mounted read-only and never written into the client config.
The image covers the service account. OAuth does not work in a container on the first run (see Docker); for OAuth, build from source.
Example prompts
- Why did my site lose clicks last week?
- Which pages rank close to page one but get almost no clicks?
- Are these URLs indexed, and what is wrong with the ones that are not?
- What should we publish next, based on the queries we already show up for?
- How is search traffic split between phones and desktops?
FAQ
How do I run Google Webtools MCP?
Run the Docker image ghcr.io/stufently/google-webtools-mcp with your service account JSON key mounted read-only and GOOGLE_APPLICATION_CREDENTIALS pointing at it, then register the same docker run command in your MCP client. For OAuth, build from source with Node.js 22 or newer.
Which Google APIs does it use?
Five: Search Console API (webmasters v3 and searchconsole v1 for URL Inspection), Google Analytics Admin API v1beta, Google Analytics Data API v1beta and Site Verification API v1.
Which AI clients does it work with?
The README has configs for Claude Code, Claude Desktop, Cursor, Windsurf, Zed and Codex. Claude Code is verified in daily use; Claude Desktop, Cursor, Windsurf and Zed are documented but not verified end to end.
Which credentials does it need?
A Google service account (GOOGLE_APPLICATION_CREDENTIALS or GOOGLE_SERVICE_ACCOUNT_KEY) added in Search Console and GA4, Application Default Credentials, or an OAuth desktop client via GSC_OAUTH_CLIENT_SECRETS_FILE. The first method that yields usable credentials wins.
Can it change my live Search Console or GA4 configuration?
Yes. add_property, delete_property, submit_sitemap, delete_sitemap, ga4_create_property, ga4_create_data_stream and gsc_verify_site change live configuration, and there is no dry-run mode.
What are the data limits?
Search Console data is typically 2–3 days behind and covers 16 months at most. Search analytics is capped at 25,000 rows per request, GA4 reports at 100,000, and batch_inspect_urls handles 50 URLs per call.
Documentation pages
- google-webtools-mcpAn MCP server that gives an AI agent direct access to Google Search Console and Google Analytics 4 — property management, search performance analysis,…