Google Webtools MCP

google-webtools-mcp

An MCP server that gives an AI agent direct access to Google Search Console and Google Analytics 4 — property management, search performance analysis, indexing checks, GA4 reporting, and site verification.

[License: MIT] [Node.js]

For AI agents

If an agent is driving this server, point it at SKILL.md first (Russian). It covers the working order — property discovery, verification, sitemaps, indexing checks, the regular audit path — how to read a URL Inspection result, what Search Console does not expose, which calls burn quota, and which tools write to live configuration.

What it does

The server exposes 39 tools built on five Google APIs:

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.

Tools

Search Console properties (4)

Sitemaps (4)

Search performance (6)

Opportunities (5)

Indexing (3)

Query analysis (3)

Reports (2)

GA4 administration (7)

GA4 reporting (3)

Site verification (2)

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/webmastershttps://www.googleapis.com/auth/analytics.readonlyhttps://www.googleapis.com/auth/analytics.edithttps://www.googleapis.com/auth/siteverification.verify_only

Option A — Service account (best for servers and automation):

1. Google Cloud Console → IAM & Admin → Service Accounts → create one.
2. Add a key → Create new key → JSON → download it.
3. In Search Console → Settings → Users and permissions → add the service account's email address.
4. In GA4 → Admin → Property access management → add the same email.

Option B — OAuth 2.0 (best for personal, local use):

1. Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app.
2. Download the client secrets JSON.
3. On first run, the server prints an authorization URL to stderr and starts a temporary local callback listener. Open the URL, consent, done.
4. The token is stored at ~/.google-webtools-mcp/token.json and refreshed automatically, so you authorize only once.

2. Environment variables

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.

1. Service account — GOOGLE_APPLICATION_CREDENTIALS, then GOOGLE_SERVICE_ACCOUNT_KEY, then ./credentials.json if its type is service_account.
2. Application Default Credentials (gcloud auth application-default login) — skipped if GOOGLE_APPLICATION_CREDENTIALS is set.
3. OAuth via GSC_OAUTH_CLIENT_SECRETS_FILE.
4. ./credentials.json in the working directory, if it looks like OAuth client secrets (has an installed or web key).

If none succeed, the server prints a setup guide and exits.

3. Install

One path, no clone and no Node.js on your machine: the server ships as a container image, ghcr.io/stufently/google-webtools-mcp (amd64 and arm64). Your MCP client starts it with docker run, and the service account key from step 1 is mounted read-only into the container. Check it starts:

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.0

It should print Server running on stdio to stderr and wait for a client (Ctrl+C to quit). The only thing to change in any block below is /absolute/path/to/service-account.json — Docker needs an absolute path.

The image covers the service account. OAuth does not work in a container on the first run (see Docker); for OAuth, build from source.

Connecting it

Every client gets the same command: docker with the arguments above.

Claude Code

claude mcp add google-webtools -- 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.0

Add --scope user to make it available in every project.

Codex

codex mcp add google-webtools -- 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.0

Or by hand, in ~/.codex/config.toml:

[mcp_servers.google-webtools]command = "docker"args = [  "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.0",]

Claude Desktop, Cursor, Windsurf

The same mcpServers block for all three; only the file differs:

{  "mcpServers": {    "google-webtools": {      "command": "docker",      "args": [        "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.0"      ]    }  }}

Restart Claude Desktop after editing the file; Cursor and Windsurf pick it up from their MCP settings page.

Zed

settings.json (zed: open settings):

{  "context_servers": {    "google-webtools": {      "command": "docker",      "args": [        "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.0"      ],      "env": {}    }  }}

Key as a string instead of a file

Where mounting a file is awkward (CI, a remote runner), pass the whole key JSON in GOOGLE_SERVICE_ACCOUNT_KEY and let Docker forward it from the environment: replace the -v … and -e GOOGLE_APPLICATION_CREDENTIALS=… arguments with -e GOOGLE_SERVICE_ACCOUNT_KEY, and set GOOGLE_SERVICE_ACCOUNT_KEY in the client's env block (or your shell). This is also what the MCP registry entry io.github.stufently/google-webtools-mcp asks for.

Build from source

Needed for OAuth, or to run without Docker. Requires Node.js 22 or newer.

git clone https://github.com/stufently/google-webtools-mcp.gitcd google-webtools-mcpnpm installnpm run build

Then use node as the command and /path/to/google-webtools-mcp/dist/cli.js as its only argument, with the credentials in env, for example:

claude mcp add google-webtools \  --env GSC_OAUTH_CLIENT_SECRETS_FILE=/path/to/client-secrets.json \  -- node /path/to/google-webtools-mcp/dist/cli.js

HTTP transport

For a client that talks to the server over the network instead of spawning it. The mode is stateless: every POST /mcp is handled by a fresh MCP server instance, no Mcp-Session-Id is issued, and requests can run in parallel. The Google credentials, cache and rate limiter are shared across requests.

node dist/cli.js --http           # listens on :3000PORT=8080 node dist/cli.js --http # or pick a port

Endpoints:

• POST /mcp — MCP JSON-RPC (Streamable HTTP). Send Accept: application/json, text/event-stream.
• GET /health — liveness, returns {"status":"ok","auth":"<method>"}.
• GET/DELETE /mcp return 405: there is no server-to-client stream and no session to terminate.

There is no authentication on the HTTP endpoint and it listens on all interfaces, while the tools act with your Google credentials (including write tools). Keep it on localhost or behind an authenticating proxy.

Docker

The OAuth consent callback listens on a random port on 127.0.0.1 inside the container, so a browser on the host cannot reach it and a first OAuth run in Docker times out. Either use a service account (mount the key and set GOOGLE_APPLICATION_CREDENTIALS), or authorize once outside Docker and copy ~/.google-webtools-mcp/token.json into the token volume.

docker compose up --build

The bundled docker-compose.yml mounts ./credentials read-only and keeps the OAuth token in a named volume so it survives container rebuilds. The Dockerfile compiles the TypeScript itself, so no local dist/ is needed; it is the same build that is published to GHCR.

Common prompts

Once connected, talk to the agent in plain language:

• "List my Search Console properties, then give me a weekly SEO report for the main one."
• "Find quick wins for https://example.com/ — pages that are close to page 1 or getting impressions but no clicks."
• "Which pages lost the most traffic in the last 28 days compared to the previous period, and why?"
• "Check whether these 12 URLs are indexed, and tell me what's wrong with the ones that aren't."
• "Create a GA4 property for example.com with a web data stream, then give me the measurement ID to install."
• "Am I cannibalizing myself anywhere? Show queries where more than one of my pages ranks."

Limitations

• Search Console data lag. Search analytics data is typically 2–3 days behind, and the lag drifts. Every named period (last7d, last28d, …) is therefore anchored to the last day the API reports as complete — read from the first_incomplete_date the API returns for a dataState: "all" query grouped by date — rather than to yesterday, so the newest days are excluded on purpose and period-over-period comparisons are not distorted by a half-collected tail. get_search_analytics still takes an explicit dataState and explicit dates when you want the fresh edge.
• 16 months of history, maximum. That is a Search Console API limit, not a server limit.
• Row sampling and caps. Search analytics is capped at 25,000 rows per request; GA4 reports at 100,000. Large GA4 date ranges may be sampled by Google.
• batch_inspect_urls handles 50 URLs per call, and the URL Inspection API has its own daily quota per property.
• Site verification is not one-click. The server hands you a token and instructions; you still have to place the file, DNS record, or meta tag yourself before calling gsc_verify_site.
• Domain properties can't use FILE or META verification — use DNS_TXT.
• No Google Ads, PageSpeed Insights, CrUX, or Indexing API. This server covers Search Console, GA4, and Site Verification only.
• Cache is in-memory and per-process. It resets whenever the server restarts and is not shared between instances.
• Write operations are real. 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. The Search Console ones are reversible by re-adding the property or re-submitting the sitemap; a created GA4 property or data stream is not something this server can remove.

Development

npm installnpm run build      # bundle with tsupnpm run dev        # rebuild on changenpm test           # vitestnpm run lint       # tsc --noEmit

Requires Node.js 22 or newer.

Releasing

The version lives in package.json. server.json (the MCP registry entry) and every ghcr.io/stufently/google-webtools-mcp:<tag> in this README are derived from it, never edited by hand:

npm version patch --no-git-tag-version   # or minor / major# Docker instead of a local Node:# docker run --rm -u "$(id -u):$(id -g)" -v "$PWD":/app -w /app node:24-slim \#   npm version patch --no-git-tag-version

npm version bumps package.json and the lockfile, then its version lifecycle script (scripts/sync-version.mjs) rewrites server.json and the image tags here (a plain npm version patch also stages them, so its own commit and tag are complete — but tag only after CI is green, as below). Add a CHANGELOG.md section, commit, push to main and wait for CI — its Versions agree step (npm run check:version) fails if any of the three disagree. Then tag and push the tag:

git tag v1.2.3 && git push origin v1.2.3

The Publish workflow builds and pushes the image (:<version> and :latest) and publishes server.json to the MCP registry; it refuses a tag that differs from package.json.

Credits

This project started as a fork of awesome-gsc-mcp by Magdoub, which provided the Search Console tools, the analysis layer (CTR benchmarks, trend detection, query classification, opportunity scoring, recommendations), the cache and the rate limiter. The GA4 Admin/Data and Site Verification tools, the authentication rework and the later fixes were added here. The original is published under the MIT license.

License

MIT — see LICENSE. The copyright notice of the original project is kept alongside this one.