Google Search Console MCP Server

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 behind a confirmation token 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 22 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.

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

Tools

site_url is optional on every tool that takes it when GSC_SITE_URL is set.

Properties and ownership

Sitemaps

Search analytics and indexing

Not exposed, on purpose

urlTestingTools.mobileFriendlyTest is still in Google's discovery document and the service behind it was switched off in December 2023. A tool for it could only ever return an error, so there is not one.

Safety

Four operations are two-step. delete_site, delete_sitemap, unverify_site and update_site_owners refuse the first call and return a short-lived token bound to those exact arguments; the second call performs the operation. A confirmation issued for one property cannot be replayed against another, and the token only ever appears in a previous tool result, so a model cannot invent it. update_site_owners is in that list because the list it takes is the complete owner list afterwards — one well-formed call removes everyone else, and nothing here can put them back.

Everything from the APIs is marked untrusted. Search queries are strings the public typed into Google; page titles and crawl diagnostics come from whoever runs the crawled site. Someone who wants a model to act on their instructions can put them in a page title and wait to be crawled. The two sentences of a confirmation prompt are built only from values the server derived; a sitemap URL or an owner list is quoted below them as data.

The allowlist has no exemptions. GSC_ALLOWED_SITES is enforced wherever a tool names a property, and separately on the two shapes that do not name one: the Indexing API tools match the page URL against the list the way Search Console scopes a property, and the verification tools resolve their opaque resource id to a property before acting on it. Both listings filter to the allowlist and say how many entries they withheld.

Read-only goes below the tool layer. GSC_READ_ONLY=true does not register the write tools and requests webmasters.readonly instead of webmasters, so a write is impossible even if a tool tried.

Credentials never leak into output. They are deleted from the environment after start-up, never sent to a redirect target, and a rejected value is described rather than echoed — including when it is a key pasted into GSC_ALLOW_TOOLS by mistake.

Development

npm install
npm test            # no network — every test runs against a stubbed fetch
npm run lint
npm run build

See CONTRIBUTING.md.

Releasing

Update CHANGELOG.md, bump the version in package.json and server.json, then push a signed tag:

git tag -s v0.1.0 -m 'v0.1.0' && git push origin main v0.1.0

release.yml runs the suite, publishes to npm with provenance through a trusted publisher, pushes the multi-arch image to GHCR and updates the MCP registry entry.