Google Search Console MCP

MCP server for the Google Search Console API: search performance analytics (clicks, impressions, CTR, position), sitemap management, URL index inspection and property management — from Claude, Cursor, Codex and other AI clients, in natural language.

Ask your assistant "which queries brought the most clicks last month?", "is this page indexed?", or "resubmit the sitemap" — it drives the Search Console API for you, from a quick indexing check to a full performance analysis.

Quick start

1. Get OAuth credentials for the Search Console API.

2. Add the server — for example, in Claude Code (other clients):

   claude mcp add google-search-console \
     -e GOOGLE_SEARCH_CONSOLE_CLIENT_ID=your_client_id \
     -e GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET=your_client_secret \
     -e GOOGLE_SEARCH_CONSOLE_REFRESH_TOKEN=your_refresh_token \
     -- npx -y mcp-google-search-console

3. Ask the assistant: "Show me the top 20 search queries for example.com over the last 28 days, with clicks and CTR."

Related MCP server: mcp-gsc

Tools

Plus resilience built in: automatic OAuth token refresh (including on 401), retries with backoff on 429 (and on 5xx/network errors for reads only — mutations are never replayed), a request timeout, and an SSRF guard so the token can't leak to a foreign host.

Example prompts

• "Which pages lost the most clicks this month compared to the previous one?"

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

• "List queries containing 'mcp' where we rank below position 10."

• "Do any of our sitemaps have errors? Resubmit the ones that do."

Two property formats (the #1 pitfall)

The site_url must match the property exactly as registered in Search Console:

• URL-prefix property — full URL with scheme and trailing slash: https://example.com/. Note http://example.com/, https://example.com/ and https://www.example.com/ are three different properties.

• Domain property — sc-domain:example.com (no scheme, no slash).

A near-match returns 403/404. list_sites shows the exact registered values — the assistant will usually call it first.

Limitations (the API's, not the server's)

• Dates are in Pacific Time and end_date is inclusive; final analytics data lags ~2–3 days (pass data_state: "all" for fresh, still-changing rows).

• Filters are AND-only — no OR across filters; regex operators use RE2 syntax.

• URL inspection quota is small: 2,000 inspections per property per day (600/minute) — don't batch-inspect entire sites.

• Search analytics: max 25,000 rows per request (paginate with start_row); anonymized long-tail queries are never returned.

• Verification is out of scope: add_site registers a property, but verification happens in the Search Console UI or the Site Verification API.

Installation

Requires Node.js 20+ (runs via npx, no separate install).

claude mcp add google-search-console \
  -e GOOGLE_SEARCH_CONSOLE_CLIENT_ID=your_client_id \
  -e GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET=your_client_secret \
  -e GOOGLE_SEARCH_CONSOLE_REFRESH_TOKEN=your_refresh_token \
  -- npx -y mcp-google-search-console

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "mcp-google-search-console"],
      "env": {
        "GOOGLE_SEARCH_CONSOLE_CLIENT_ID": "your_client_id",
        "GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_SEARCH_CONSOLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

~/.cursor/mcp.json (or .cursor/mcp.json in the project)

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "mcp-google-search-console"],
      "env": {
        "GOOGLE_SEARCH_CONSOLE_CLIENT_ID": "your_client_id",
        "GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_SEARCH_CONSOLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

.vscode/mcp.json — note the servers key (not mcpServers)

{
  "servers": {
    "google-search-console": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-search-console"],
      "env": {
        "GOOGLE_SEARCH_CONSOLE_CLIENT_ID": "your_client_id",
        "GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_SEARCH_CONSOLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Getting credentials

The Search Console API has no API-key access — every call needs OAuth 2.0 (the data belongs to your account). One-time setup, ~10 minutes:

1. Create a Google Cloud project (or reuse one) at console.cloud.google.com, then enable the Google Search Console API: APIs & Services → Library → Google Search Console API → Enable.

2. Configure the OAuth consent screen (APIs & Services → OAuth consent screen): choose External, fill in the app name and your email, and add your Google account under Test users (in Testing mode only listed users can authorize — no app verification needed).

3. Create an OAuth client (APIs & Services → Credentials → Create credentials → OAuth client ID), application type Desktop app. Save the client ID and client secret.

4. Mint a refresh token. The easiest way is the OAuth 2.0 Playground:

   • Click the gear icon → check Use your own OAuth credentials → paste your client ID and secret (add https://developers.google.com/oauthplayground as an authorized redirect URI to the OAuth client first).

   • In Step 1, enter the scope https://www.googleapis.com/auth/webmasters and click Authorize APIs, signing in with the test-user account that owns your Search Console properties.

   • In Step 2, click Exchange authorization code for tokens and copy the refresh token.

5. Put the three values into GOOGLE_SEARCH_CONSOLE_CLIENT_ID, GOOGLE_SEARCH_CONSOLE_CLIENT_SECRET and GOOGLE_SEARCH_CONSOLE_REFRESH_TOKEN. The server exchanges the refresh token for short-lived access tokens automatically.

Scope notes: https://www.googleapis.com/auth/webmasters covers everything including sitemap submission and property management. If you only need reads (analytics, inspection, listings), the narrower https://www.googleapis.com/auth/webmasters.readonly works — but add_site, delete_site, submit_sitemap and delete_sitemap will then return 403. While the consent screen stays in Testing mode, refresh tokens expire after 7 days — publish the app (or keep it Internal in a Workspace domain) for long-lived tokens.

⚠️ The credentials are stored in plain text in your client's config — treat them like a password. The refresh token grants access to your Search Console data until revoked at myaccount.google.com/permissions.

Configuration

* Either the three refresh-flow variables together, or GOOGLE_SEARCH_CONSOLE_ACCESS_TOKEN.

Documentation

• All tools — full reference with parameters and notes.

• Development — build, tests, smoke check, telemetry.

• Publishing — releasing and MCP-catalog listing.

Support

Questions, ideas, issues — Telegram @gistrec or GitHub issues.

License

MIT — see LICENSE.