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

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

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.

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

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

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

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.

Cursor

~/.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.0"
      ]
    }
  }
}

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

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

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 and uploads
dist-mcpb/*.mcpb 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.