Google Search Console

io.github.acamolesePublished by GitHub account acamolesev3.0.1Updated Oct 25, 2026

Google Search Console: SEO audits, performance queries, URL inspection, indexing checks.

VerifiedSTDIODesktop onlyWeb Search & ScrapingData & Analytics

Overview

AI-generated overview

Read-only Google Search Console server for SEO audits: query performance data, inspect URLs, check indexing and sitemaps, and generate HTML audit reports.

What you can do
List properties and show permission level and type for each one, plus a portfolio overview ranked worst first and a configuration/API health check (gsc_doctor). Query Search Analytics with filters, dimensions and pagination, and compare periods, performance overviews, quick wins, CTR gaps, cannibalisation, traffic drops, content decay and alerts. Check indexing status for a list of URLs and run full URL Inspection on a single page. List known sitemaps with their errors and warnings. Generate a self-contained, white-label HTML audit report in English or Italian, with branding and thresholds from a JSON file.
When to use it
Useful for SEO work on sites you can read in Search Console: weekly performance reviews, indexing audits, finding cannibalisation or CTR gaps, diagnosing traffic drops, and producing a client-ready audit report an agency can brand.
Requirements
Runs locally as a Python package via uvx (uv must be installed) or as a Docker container. Needs Google Search Console API access: an OAuth Desktop app client (GSC_CLIENT_ID, GSC_CLIENT_SECRET, GSC_REFRESH_TOKEN, obtained with the auth command), a service account key (GSC_SERVICE_ACCOUNT_FILE or GSC_SERVICE_ACCOUNT_JSON), or Application Default Credentials. Network access to Google's API.
Before you install
Requires OAuth client credentials and a refresh token, or a service account private key file; these are secrets and should be kept out of shared configs. The scope is read-only (webmasters.readonly) and no tool modifies properties or sitemaps. The optional Docker container speaks streamable HTTP with no authentication of its own, so keep it on loopback or behind a reverse proxy. Subject to Google quotas, including a daily URL Inspection limit per property.

Installation

In SourceWeft

  1. Open Google Search Console in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Google Search Console MCP

English · Italiano

[CI] [PyPI] [Python] [License: MIT]

Seventeen 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

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:

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
# Codexcodex mcp add google-search-console -- uvx mcp-google-search-console
# Gemini CLIgemini mcp add google-search-console uvx mcp-google-search-console

Docker

bash
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:

    bash
    export GSC_CLIENT_ID="...apps.googleusercontent.com"export GSC_CLIENT_SECRET="..."uvx mcp-google-search-console auth

  3. The browser flow prints the three export lines for a stateless setup, and also stores a token at ~/.config/mcp-google-search-console/token.json with 0600 permissions.

On a headless machine, run auth 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:

bash
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
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_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, run server-sideraw rows, analysed by the model
ThresholdsAdapt to the size of the propertyfixed, or none
Datesperiod="last_month", days=28, resolved server-sideexplicit dates only
FreshnessdataState=all by default, matching the UIfinal only
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
Tests280+, 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:

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

  • 16 months of daily data. Anything older is not available at any price.
  • Hourly data: the last 10 days only.
  • URL Inspection: 600 per minute and 2,000 per day per property. This is the limit that bites on a large site.
  • Search Analytics: 1,200 queries per minute per site. Responses are cached in memory for 6 hours (1 hour for inspections); no_cache=true bypasses it.
  • Rows: 25,000 per API call. Tools default to 100 and cap at 1,000, with start_row for pagination; the cap is reported in the response, never applied silently.

Environment variables

VariableDefaultPurpose
GSC_CLIENT_ID, GSC_CLIENT_SECRET, GSC_REFRESH_TOKENStateless OAuth
GSC_SERVICE_ACCOUNT_FILE, GSC_SERVICE_ACCOUNT_JSONService account
GSC_AUTH_MODEautoForce oauth, service_account or adc
GSC_REPORT_LANGUAGEenReport language: en or it
GSC_DATA_STATEallall includes today's partial data, final does not
GSC_CACHE_TTL_SECONDS21600Response cache TTL; 0 disables it
GSC_INSPECT_CONCURRENCY5Parallel URL inspections
GSC_LOG_LEVELWARNINGLogging, always to stderr
MCP_TRANSPORT, MCP_HOST, MCP_PORTstdioTransport

Troubleshooting

spawn uvx ENOENT — the client cannot find uvx on its PATH. GUI apps do not inherit a shell PATH. Use the absolute path: which uvx gives it, typically /Users/you/.local/bin/uvx.

403 forbidden on every call — almost always the property format. A domain property is sc-domain:example.com; a URL-prefix property is https://example.com/, trailing slash included. gsc_sites returns the exact strings.

401 invalid_grant — the refresh token was revoked or expired. Google expires refresh tokens for OAuth apps still in "testing" after seven days; publish the app, or re-run auth.

403 quotaExceeded — the daily URL Inspection quota is gone. It resets tomorrow; nothing retries past it.

Empty report on a small site — check the thresholds in the response meta. They adapt to the property, but the floors (50 impressions, 10 clicks) still apply. Pass thresholds to lower them.

Anything else — run doctor and include its output in the issue.

Security

  • Read-only scope, requested and never widened.
  • Token files are written atomically with 0600 permissions. Credentials supplied through the environment are never written to disk.
  • gsc_doctor masks the client ID and never returns a token.
  • No telemetry, no analytics, no request to any host other than Google's API.

See SECURITY.md for the reporting policy.

Development

bash
uv venv && uv pip install -e ".[dev]"ruff check src tests scripts && ruff format --check src tests scriptspytest -q --cov=google_search_console_mcppython scripts/sync_versions.pypython scripts/render_sample_report.py --lang it --open

Tests never hit the network. Live tests exist behind -m live and require GSC_LIVE_TESTS=1 plus credentials; they never run in CI.

Releases: see docs/RELEASING.md. Decisions not covered by the code are logged in docs/DECISIONS.md.

License

MIT. Chart.js 4.5.1 is vendored under src/google_search_console_mcp/static/, also MIT, with its licence alongside.

Source: README.md at commit 3bba49f

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v3.0.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts