search-console-mcp

MCP server for Google Search Console that exposes the official Search Console API as tools for AI agents.

Its focus is search performance and index health — querying clicks, impressions, CTR and position by query, page, country, device or date, checking whether a URL is indexed and why not, and managing the sitemaps and properties of an account.

What it deliberately does not do: no requesting (re)indexing of URLs — the separate Indexing API only supports job posting and livestream pages — no property ownership verification (an owner must add the service account to each property), and no Google Analytics data (that is the unrelated Analytics Data API).

Deletes are opt-in. delete_sitemap and delete_site are only registered when GOOGLE_SEARCH_CONSOLE_ALLOW_DESTRUCTIVE is set — see Configuration.

Install

claude mcp add search-console \
  -e GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
  -e GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
  -- npx -y @orellbuehler/search-console-mcp

The -e flags must come before the -- separator; anything after -- is passed to the server process instead of being read as configuration.

Getting a service account key

1. In the Google Cloud console, select or create a project and enable the Google Search Console API.

2. Go to IAM & Admin → Service accounts → Create service account. You can skip the optional "grant access" steps — Search Console permissions are granted separately, not via Cloud IAM roles.

3. Open the new service account, go to the Keys tab, and choose Add key → Create new key → JSON. The file downloads once and cannot be retrieved again.

4. In Search Console, open the property, go to Settings → Users and permissions → Add user, and paste the service account's email address (name@project-id.iam.gserviceaccount.com). Grant:

   • Restricted or Full for the read tools (analytics, sitemaps, URL inspection)

   • Full for submit_sitemap and delete_sitemap

5. Repeat step 4 for every property the server should see — a service account cannot verify properties itself.

6. Point GOOGLE_SERVICE_ACCOUNT_KEY_PATH at the downloaded JSON file.

Treat the JSON key like a password — it carries whatever permissions you granted, with no second factor in front of it. Keep it outside the repository and consider chmod 600.

Configuration

A property is identified either as a URL-prefix property like https://example.com/ (protocol and trailing slash matter — https://example.com/ and http://example.com/ are different properties) or as a domain property like sc-domain:example.com, which covers all subdomains and protocols. Use whichever form the property was added to Search Console with; list_sites shows the exact strings.

Usage with Claude Code

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@orellbuehler/search-console-mcp"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY_PATH": "/path/to/service-account.json",
        "GOOGLE_SEARCH_CONSOLE_SITE_URL": "https://example.com/"
      }
    }
  }
}

Example prompts

• "What are my top search queries this month?"

• "Which pages get the most clicks from Google, and how did that change vs the previous 28 days?"

• "Show queries containing 'pricing' where we rank below position 10 — quick-win candidates."

• "How much of our traffic is mobile vs desktop?"

• "Plot our daily clicks and impressions over the last three months."

• "Which countries do we get impressions from but almost no clicks?"

• "Is https://example.com/blog/launch indexed? If not, why?"

• "List our sitemaps and tell me if any have errors or warnings."

• "Resubmit the sitemap after yesterday's site restructure."

• "Which pages ranking for 'mcp server' compete with each other?"

• "Compare our Discover traffic to web search traffic this quarter."

Tools

Search analytics

Sitemaps

Sites

URL inspection

Notes & caveats

• Performance data lags ~2–3 days. The convenience tools default their date range to end 3 days ago; data_state: "all" includes fresh but possibly incomplete data.

• 16-month retention. Queries older than that return no rows.

• Privacy filtering. Rows for rare queries are withheld, so summing per-query rows undercounts the true totals; query without dimensions for exact totals.

• 25,000 rows per call. Paginate with start_row; a response with fewer rows than row_limit is the last page.

• URL inspection quota is about 2,000 calls/day per property and 600/minute — inspect selectively, not in bulk.

• The hour dimension requires data_state: "hourly_all" and only covers the last ~10 days.

• Your search data goes to the LLM. Everything a tool returns becomes model context; don't connect properties whose data must not leave your environment.

Development

npm install
npm run build         # tsc -p tsconfig.build.json -> dist/
npm test              # vitest run
npm run lint          # eslint src
npm run typecheck     # tsc --noEmit
npm run format        # prettier --write .

Smoke-test the built server against a real property:

GOOGLE_SERVICE_ACCOUNT_KEY_PATH=/path/to/service-account.json \
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://example.com/ \
npx @modelcontextprotocol/inspector node dist/index.js

CI / Releasing

CI runs format:check, lint, typecheck, test and build on Node 20 and 22. Publishing happens on GitHub release via npm trusted publishing (OIDC, no tokens):

npm version patch
git push --follow-tags
gh release create "v$(node -p "require('./package.json').version")" --generate-notes

License

MIT © Orell Bühler