Google Webtools MCP README

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.

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/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):

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

Verified clients and platforms

Only what has actually been run is listed as verified. Everything else in Connecting it is a documented config that nobody has checked end to end.

Connecting it

Each block below starts the server with docker and the arguments from the install command above. The only thing to change is /absolute/path/to/service-account.json.

Claude Code

Project file .mcp.json, at the root of the project:

{
  "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.2"
      ]
    }
  }
}

The same server can be registered from a terminal:

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

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

Claude Desktop

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json, Linux ~/.config/Claude/claude_desktop_config.json. Restart Claude Desktop after saving.

{
  "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.2"
      ]
    }
  }
}

Claude Desktop can also install this server in one click. Download the .mcpb from https://github.com/stufently/google-webtools-mcp/releases/latest and open it. Desktop asks for the service account JSON key, which must belong to an account added in Search Console and GA4.

The same release includes checksums.txt with a SHA256 for each .mcpb. Download that file next to the bundle and check it:

sha256sum -c --ignore-missing checksums.txt   # run next to the downloaded .mcpb

On macOS, shasum -a 256 -c --ignore-missing checksums.txt does the same check.

Releases from the next tag on also carry a GitHub build provenance attestation for each .mcpb, signed in the release workflow. Check that a bundle was built by this repository's workflow and not swapped afterwards (needs the GitHub CLI):

gh attestation verify <bundle>.mcpb --repo stufently/google-webtools-mcp

Cursor

After installing, replace /absolute/path/to/service-account.json in ~/.cursor/mcp.json with the path to your key file. Or add the block below by hand.

~/.cursor/mcp.json, or .cursor/mcp.json in a project:

{
  "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.2"
      ]
    }
  }
}

Windsurf

mcp_config.json. On macOS and Linux that is ~/.config/devin/mcp_config.json (or $XDG_CONFIG_HOME/devin/mcp_config.json). On Windows it is %APPDATA%\devin\mcp_config.json. Older builds used ~/.codeium/windsurf/mcp_config.json.

{
  "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.2"
      ]
    }
  }
}

Zed

Zed calls MCP servers context servers. The file is 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.2"
      ],
      "env": {}
    }
  }
}

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

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.2",
]

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 the variable in your shell (export GOOGLE_SERVICE_ACCOUNT_KEY="$(cat service-account.json)") or in the client's env block. Inside a JSON or TOML config the key must be a single escaped string, not pasted JSON: jq -c . service-account.json | jq -R . prints it ready to paste. 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.git
cd google-webtools-mcp
npm install
npm 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 :3000
PORT=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 (the install command above), 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.

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?

More prompts

• Create a GA4 property for example.com with a web stream and give me the measurement id to install.
• Where are my own pages competing for the same query?

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 install
npm run build      # bundle with tsup
npm run dev        # rebuild on change
npm test           # vitest
npm 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. The MCPB workflow, on the same tag, builds the Desktop Extension with scripts/build-mcpb.sh, writes dist-mcpb/checksums.txt, attests build provenance for every bundle, and uploads the .mcpb bundles and that checksum file to the GitHub Release. It does not push the image or the registry entry.

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.