Google Search Console: SEO audits, performance queries, URL inspection, indexing checks.
io.github.acamolese/google-search-console-mcp — Model Context Protocol Server
This MCP server integrates with Google Search Console to support SEO audits, performance queries, URL inspection, and indexing checks. It is packaged as a Python MCP server with repository metadata and usage oriented around search-console-api workflows.
🛠️ Key Features
SEO audits
Performance queries
URL inspection
Indexing checks
🚀 Use Cases
Investigating site performance in Google Search Console
Checking specific URLs for status and indexing issues
Running repeatable SEO audit and reporting workflows
⚡ Developer Benefits
Topics aligned with SEO automation and SEO tooling (e.g., seo-audit, seo-reporting)
Python/MCP-focused ecosystem support (mcp, mcp-server, llm-tools)
Includes documented repository/project identifiers and language references in the readme excerpt
⚠️ Limitations
Server capabilities described here are limited to the listed Search Console tasks (audits, performance queries, URL inspection, indexing checks)
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
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:
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
Tool
What it answers
gsc_sites
Which properties can this account read, and in what exact format
gsc_site_details
Permission level and type for one property
gsc_query
The Search Analytics report, with filters, dimensions and pagination
gsc_performance_overview
Is the site up or down, against the previous period
gsc_compare_periods
What changed between two periods, ranked by click delta
gsc_quick_wins
Queries close enough to the top that a push would pay off
gsc_ctr_gaps
Pages that rank but are not clicked
gsc_cannibalization
Queries where several pages compete against each other
gsc_traffic_drops
Pages that lost clicks, with a likely cause for each
gsc_content_decay
Pages sliding down month after month
gsc_alerts
What moved sharply enough to be worth a message today
gsc_portfolio
Every property at a glance, worst first
gsc_indexing_issues
Which of these URLs are indexed, and why not
gsc_inspect_url
Full URL Inspection for one page
gsc_sitemaps
Which sitemaps Google knows about, with errors and warnings
gsc_doctor
What is configured, and does the API answer
gsc_audit
The full HTML report
Three prompts wrap the workflows that repeat: gsc_weekly_report,
gsc_indexing_audit, gsc_content_opportunities.
Why this server
Here
Typical GSC MCP server
Client-ready report
Self-contained HTML, English or Italian, white-label
none
Analysis
Cannibalisation, CTR gaps, decay, drop diagnosis, run server-side
TSV by default, roughly a third of the tokens of pretty JSON
json.dumps(indent=2)
Errors
Google's reason plus what to do about it
bare HTTP status
Tests
280+, on both mcp majors, three operating systems
usually 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:
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.
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.
