Google Search Console MCP logo

Google Search Console MCP

by acamolese

Read-only Google Search Console data, URL inspection, indexing checks, sitemaps, and HTML SEO audit reports through MCP.

Install Google Search Console MCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "acamolese-google-search-console-mcp": {
      "command": "uvx",
      "args": [
        "mcp-google-search-console"
      ],
      "env": {
        "GSC_CLIENT_ID": "YOUR_VALUE_HERE",
        "GSC_CLIENT_SECRET": "YOUR_VALUE_HERE",
        "GSC_REFRESH_TOKEN": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Automated check passed— started and listed 18 tools correctly ().

Overview

This MCP server connects AI assistants to Google Search Console using a read-only OAuth scope. It supports performance analysis, site and sitemap discovery, URL inspection, indexing checks, and generated HTML audits with 30/60/90-day roadmaps. Use it for SEO analysis without changing Search Console properties.

Use cases

  • Analyze clicks, impressions, CTR, and average position
  • Inspect URLs and identify indexing issues
  • Review queries by page, country, device, or date
  • List verified properties and submitted sitemaps
  • Generate branded HTML SEO audit reports

Key features

  • Read-only Google Search Console OAuth access
  • Performance reports with query, page, country, device, and date dimensions
  • URL inspection and indexing status checks
  • Verified site and sitemap listing
  • HTML SEO audits with Chart.js graphs and 30/60/90-day roadmaps
  • Custom report branding with logos, fonts, and color palettes

Tools18

What Google Search Console MCP lets your agent do. Expand a tool for its parameters.

Verified live~8.8k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked

Recent health check succeeded.

21/21 checks healthy over the last 104d

What it can do

From the 18 tools this server returned when we ran it; 18 declare their own safety hints.

Handles credentials · 1Makes network requests · 18Read-only tools · 18
Network at startup2 connections
Files written at startup10

Observed 2026-11-15 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 15d ago via OSV.dev · mcp-google-search-console (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars11Stargazers on the source repository.
Last commit8d agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed18Callable tools this server registers over MCP.
Directory activity5 viewsConfig copies, upvotes, and views on AllMCPs.

From the project README

Google Search Console MCP

English · Italiano

CI PyPI Python License: MIT

Eighteen read-only tools over the Google Search Console API, plus a deterministic white-label HTML audit report an agency can put its own name on and send to a client, in English or Italian.

The generated audit report

Regenerate that report from committed synthetic data, with no credentials:

bash
python scripts/render_sample_report.py --lang en --open

What's new in 4.0

4.0 is about trust: every number the server reports now says what it is based on, and nothing incomplete is presented as a finding.

  • Comparisons hold whole days. Search Console's latest days are partial for a while, so a 7-day window ending today used to start 15-20% down against the week before. Comparison tools now end rolling windows on the last day with final data and report it as data_through.
  • Year over year. compare="year" on the overview, period comparison, traffic drops, alerts and the audit. Whole months map to the same months last year; other ranges move back 52 weeks so weekdays line up.
  • Filters everywhere. The analysis tools and gsc_compare_periods accept the same filters and type as gsc_query: analyse /blog/, one country, mobile only, or Discover.
  • Brand vs non-brand, done properly. The new gsc_brand_split tool, and the audit, compute the split over every query with server-side regex filters and report the clicks Google does not disclose as a third share. Brand terms match whole words only.
  • No more false alarms. Content decay compares complete months only. A page below a row limit is no longer reported as lost. A failed URL Inspection is no longer an indexing problem. Cannibalisation leaves out brand queries and queries one page clearly owns.
  • A sounder report. One definition of a low CTR, thresholds per kind of row, inspection of the pages that lost clicks, a "pages in steady decline" section, a "how to read this report" section, translated verdicts, darker default colours and accessible charts and tables. The pagination advice no longer recommends canonicalising to page one.

Upgrading from 3.x: see the breaking changes at the top of the changelog.

Install

Claude Code

bash
/plugin marketplace add acamolese/google-search-console-mcp
/plugin install google-search-console@acamolese

The plugin brings the MCP server, five skills (weekly review, cannibalisation check, indexing audit, content opportunities, white-label client audit) and a config prompt for the three credentials.

Claude Desktop

Download google-search-console.mcpb from the latest release and open it. It needs uv installed. Or edit the config file directly:

config.json
{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"],
      "env": {
        "GSC_CLIENT_ID": "...",
        "GSC_CLIENT_SECRET": "...",
        "GSC_REFRESH_TOKEN": "..."
      }
    }
  }
}

Cursor, Codex, Gemini CLI, Zed

Any MCP client takes the same three lines: command uvx, argument mcp-google-search-console, and the three GSC_* environment variables.

bash
# Codex
codex mcp add google-search-console -- uvx mcp-google-search-console

# Gemini CLI
gemini mcp add google-search-console uvx mcp-google-search-console

Docker

Terminal
docker build -t mcp-gsc .
docker run --rm -p 127.0.0.1:8765:8765 \
  -e GSC_CLIENT_ID -e GSC_CLIENT_SECRET -e GSC_REFRESH_TOKEN \
  -v "$PWD/reports:/reports" mcp-gsc

The container speaks streamable HTTP on /mcp. It has no authentication of its own: keep it on loopback or behind a reverse proxy.

Authentication

The OAuth scope is webmasters.readonly and nothing else. No tool in this server can modify a property, a sitemap or anything else in Search Console.

Credentials are resolved in this order:

  1. GSC_AUTH_MODE if set (oauth, service_account, adc)
  2. GSC_SERVICE_ACCOUNT_FILE or GSC_SERVICE_ACCOUNT_JSON
  3. GSC_CLIENT_ID + GSC_CLIENT_SECRET + GSC_REFRESH_TOKEN
  4. A token file in ~/.config/mcp-google-search-console/
  5. Application Default Credentials

OAuth, once

  1. In Google Cloud Console, enable the Google Search Console API and create an OAuth client of type Desktop app.

  2. Export the client, or save the downloaded JSON as ~/.config/mcp-google-search-console/oauth_credentials.json:

    server.ts
    export GSC_CLIENT_ID="...apps.googleusercontent.com"
    export GSC_CLIENT_SECRET="..."
    uvx mcp-google-search-console auth
    
  3. The browser flow stores a token at ~/.config/mcp-google-search-console/token.json with 0600 permissions. Secrets are never printed by default; add --print-env to also get the three export lines for a stateless setup.

On a headless machine, run auth --print-env on your laptop and copy the three environment variables across. --no-browser prints the URL instead of opening one, but still needs a local redirect.

Service account

Grant the service account's email read access to the property in Search Console, then point the server at the key:

server.ts
export GSC_SERVICE_ACCOUNT_FILE=/path/to/key.json
# or, for a container:
export GSC_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'

Check it works

bash
uvx mcp-google-search-console doctor

Prints the auth mode in use, when the token expires, how many properties the account can read, and the defaults every tool applies. Secrets are masked. Exits 1 when nothing resolves, which is the answer to most "the server won't start" reports.

Tools

ToolWhat it answers
gsc_sitesWhich properties can this account read, and in what exact format
gsc_site_detailsPermission level and type for one property
gsc_queryThe Search Analytics report, with filters, dimensions and pagination
gsc_performance_overviewIs the site up or down, against the previous period or last year
gsc_compare_periodsWhat changed between two periods, ranked by click delta
gsc_quick_winsQueries close enough to the top that a push would pay off
gsc_ctr_gapsPages that rank but are not clicked
gsc_cannibalizationQueries where several pages compete against each other
gsc_traffic_dropsPages that lost clicks, with a likely cause for each
gsc_brand_splitBrand, non-brand and undisclosed clicks, month by month
gsc_content_decayPages sliding down month after month
gsc_alertsWhat moved sharply enough to be worth a message today
gsc_portfolioEvery property at a glance, worst first
gsc_indexing_issuesWhich of these URLs are indexed, and why not
gsc_inspect_urlFull URL Inspection for one page
gsc_sitemapsWhich sitemaps Google knows about, with errors and warnings
gsc_doctorWhat is configured, and does the API answer
gsc_auditThe full HTML report

Three prompts wrap the workflows that repeat: gsc_weekly_report, gsc_indexing_audit, gsc_content_opportunities.

Why this server

HereTypical GSC MCP server
Client-ready reportSelf-contained HTML, English or Italian, white-labelnone
AnalysisCannibalisation, CTR gaps, decay, drop diagnosis, brand split, run server-sideraw rows, analysed by the model
HonestyTruncation, skipped sections and anchors declared in every responsesilent gaps
ThresholdsAdapt to the size of the propertyfixed, or none
Datesperiod="last_month", days=28, resolved server-sideexplicit dates only
Freshnessgsc_query matches the UI; comparisons end on the last day with final datawindows that end on partial days
AuthOAuth, service account, ADCOAuth only
OutputTSV by default, roughly a third of the tokens of pretty JSONjson.dumps(indent=2)
ErrorsGoogle's reason plus what to do about itbare HTTP status
Tests350+, on both mcp majors, three operating systemsusually none

Report customisation

Colours, logo, report name, brand terms and thresholds come from a JSON file. Pass branding_path, or place it at ~/.config/mcp-google-search-console/branding.json to apply it everywhere:

config.json
{
  "brand_name": "Your Agency",
  "logo": "logo.png",
  "brand_terms": ["clientbrand", "client brand"],
  "colors": { "primary": "#2b6cb0", "primary_dark": "#1a365d" },
  "thresholds": { "min_impressions": 200 }
}

A local logo is base64-encoded into the document. A remote one is only kept if allow_external_fonts is true, because the report is otherwise guaranteed to contain no external URL at all: no CDN, no font service, nothing that phones home when a client opens it.

brand_terms matters more than it looks. Without it, the first label of the domain is used as the brand, which is wrong for abbreviations, holding companies and invented names, and it silently mislabels the brand/non-brand split. The report says when it had to guess.

Quotas and limits

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Google Search Console MCP

No. It uses the webmasters.readonly OAuth scope and provides read-only access.

It can query performance metrics including clicks, impressions, CTR, and position, with dimensions such as query, page, country, device, and date.

Yes. The server provides indexing checks for page lists and detailed URL Inspection for individual pages.

The gsc_audit tool generates a self-contained HTML SEO report for a selected date range.

Related MCP servers

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewGoogle Search Console MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/acamolese-google-search-console-mcp?style=directory)](https://allmcps.com/mcp/acamolese-google-search-console-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/acamolese-google-search-console-mcp"><img src="https://allmcps.com/api/badge/acamolese-google-search-console-mcp?style=directory" alt="Google Search Console MCP on AllMCPs" /></a>