Google Search Console

google-search-console-mcp

A Model Context Protocol (MCP) server for Google Search Console, the service that tells you how Google sees your site — this reads it and sets it up.

Lets MCP clients like Claude Code, Claude Desktop or Codex create a property and prove ownership of it, submit and refresh sitemaps, ask what any URL's index status is, and query the whole Performance report — with the irreversible operations put to a person first and the write tools switchable off entirely.

21 tools is the ceiling, not the floor: GSC_ALLOW_TOOLS=essential registers a curated five instead, and a model picks the right tool far more reliably from five than from 21 — see choosing which tools load.

What makes it different

It can actually create a working property. Getting one takes four steps in a fixed order — obtain a verification token, place it in DNS or on the page, verify ownership, add the property — and nothing in Google's APIs enforces that order. Calling sites.add first _succeeds_ and leaves a property that appears in every listing and answers 403 for every piece of data, which looks like a permissions bug and is not. setup_site reports which step is missing and hands over the exact DNS record to paste. Servers that expose sites.add alone can only add properties somebody already verified by hand.

Three APIs, not one. Search Console v1 is ten methods and does not include ownership. Site Verification is a separate service with its own scope, its own host and an incompatible way of naming the same site — sc-domain:example.com there is {type: INET_DOMAIN, identifier: example.com}, and passing the property spelling straight through is accepted and verifies a domain literally called sc-domain:example.com. The Indexing API is a third. All three are covered, and the translation between them is in src/site-identity.ts.

The numbers are right. Search analytics come back as a table with totals where CTR is computed from the totals rather than averaged across rows, and average position is weighted by impressions. Unweighted, a thousand rare queries ranking 80th drag a property's real average of 12 up into the nineties. The result also says plainly that the rows do not sum to the property total when the query dimension is used — Google withholds rare queries for anonymity, commonly a third or more of all impressions, and a total printed without that caveat is a number people will quote.

It knows where these APIs are sharp. The trailing slash on https://example.com/ is mandatory and its absence is a 403; a domain property and a URL-prefix property for the same site are different properties with different data, so a bare hostname is refused rather than guessed at; days are counted in Pacific Time, so a last7days computed in UTC asks for a day Google has no data for; the hour dimension silently returns nothing without dataState: HOURLY_ALL; Google omits empty arrays entirely, so a fresh credential's property list arrives as {}; and the Indexing API returns 200 for any owned URL while only acting on JobPosting and BroadcastEvent pages.

Requirements

• Node.js 24 or newer (or the container image)
• A Google credential — a service account key, an OAuth2 refresh token, or application default credentials
• The APIs you intend to use enabled in a Google Cloud project: Search Console API, and separately Site Verification API and Indexing API

Configuration

The server starts without credentials and lists its tools; every call then fails with setup instructions rather than a Google error. That is deliberate, so registries and sandbox inspectors can introspect it.

Credentials are tried in that order — explicit beats ambient. A partial OAuth triple is a startup error rather than a reason to fall through to application default credentials, because that fallback would quietly run the server as whatever account the machine is logged into.

Which credential

A service account is the recommended one: it sees only the properties you explicitly add it to, and revoking it does not touch anyone's Google account. Add its client_email under Settings → Users and permissions in Search Console, or give it ownership with verify_site. Note that the Indexing API requires owner, not full user.

An OAuth2 refresh token acts as the person who consented and sees everything they see. Its scopes were fixed at consent time and cannot be widened later.

Choosing which tools load

Every visible tool costs context on every request, and a model picks the right one far more reliably from five than from 21. Two variables narrow the list:

GSC_ALLOW_TOOLS=essential          # the curated five

GSC_ALLOW_TOOLS='list_*,get_site' # exact names, or one trailing * GSC_DENY_TOOLS='delete_*' # subtracted from whatever allow left

essential is list_sites, get_site, list_sitemaps, query_search_analytics and inspect_url — everything needed to look at a property, and nothing that changes it.

An entry that matches no tool stops the server with the list of real names. An ignored typo would otherwise leave a tool missing from tools/list with nothing pointing at the cause, and nobody traces an absence back to an environment variable.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Narrowing the list also narrows the credential: the OAuth scopes this server requests are derived from the tools that are actually registered, so a server denied the Indexing tools never asks for the Indexing scope.

Installation

Claude Code

claude mcp add google-search-console -- npx -y @ni-c/google-search-console-mcp

Claude Desktop

{

"mcpServers": { "google-search-console": { "command": "npx", "args": ["-y", "@ni-c/google-search-console-mcp"], "env": { "GSC_SERVICE_ACCOUNT_KEY_FILE": "/path/to/key.json", "GSC_SITE_URL": "sc-domain:example.com" } } } }

Codex

[mcp_servers.google-search-console]

command = "npx" args = ["-y", "@ni-c/google-search-console-mcp"]

[mcp_servers.google-search-console.env] GSC_SERVICE_ACCOUNT_KEY_FILE = "/path/to/key.json" GSC_SITE_URL = "sc-domain:example.com"

Docker

docker run --rm -i \

-v /path/to/key.json:/key.json:ro \ -e GSC_SERVICE_ACCOUNT_KEY_FILE=/key.json \ -e GSC_SITE_URL=sc-domain:example.com \ ghcr.io/ni-c/google-search-console-mcp

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches google-search-console-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{

"mcpServers": { "google-search-console": { "command": "npx", "args": ["-y", "@ni-c/google-search-console-mcp"], "env": { "GSC_SERVICE_ACCOUNT_KEY": "…", "GSC_SITE_URL": "sc-d