SkillAgentSearch skills...

google-search-console-mcp

MCP server for Google Search Console: 17 read-only tools covering performance queries, quick wins, CTR gaps, cannibalisation, traffic-drop diagnosis and indexing, plus a self-contained white-label HTML SEO audit in English or Italian. Claude Code plugin, .mcpb bundle, Docker.

Install / Use

claude mcp add acamolese -- npx -y github:acamolese/google-search-console-mcp

If the server publishes to npm under a different name, use that package instead โ€” check the repo README.

About this skill
๐Ÿ”Œ

MCP Server

Model Context Protocol server

Quality Score

83/100

Category

Automation

Supported Platforms

Claude Code
Claude Desktop
Cursor
Zed

Our assessment of google-search-console-mcp

google-search-console-mcp scores 83/100 on our quality scale, 2126th of 2,790 Automation skills we index.

Its MCP Server is 11 KB long, well organised into 22 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.

It has 10 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
29/30
Structure
20/20
Description
15/15
Adoption
4/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 2 days ago, so google-search-console-mcp is actively maintained.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit โ€” read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-14. Automated pattern scan on 2026-11-14. It catches known dangerous patterns, not every risk โ€” read a skill before letting an agent act on it.

google-search-console-mcp compared with similar skills

All 4 of these similar skills score higher than google-search-console-mcp; compare them before choosing.

SkillScoreStarsUpdatedFormat
google-search-console-mcp (this skill)by acamolese83102d agoMCP Server
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
CowAgentby zhayujie10048.0ktodayCLAUDE.md

Frequently asked questions

How do I install google-search-console-mcp?
Run claude mcp add acamolese -- npx -y github:acamolese/google-search-console-mcp. The install tabs above show the steps for each supported agent.
Which AI agents does google-search-console-mcp work with?
It is written for Claude Code, Claude Desktop, Cursor and Zed, as a MCP Server file. Other agents that read the same format can often use it too.
Is google-search-console-mcp safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is google-search-console-mcp still maintained?
The repository was last updated 2 days ago, so google-search-console-mcp is actively maintained.
<!-- mcp-name: io.github.acamolese/google-search-console-mcp -->

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:

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

Install

Claude Code

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

{
  "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.

# 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

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:

    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:

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

Check it works

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 | raw rows, analysed by the model | | Thresholds | Adapt to the size of the property | fixed, or none | | Dates | period="last_month", days=28, resolved server-side | explicit dates only | | Freshness | dataState=all by default, matching the UI | final only | | Auth | OAuth, service account, ADC | OAuth only | | Output | 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:

{
  "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

| Variable | Default | Purpose | |---|---|---| | GSC_CLIENT_ID, GSC_CLIENT_SECRET, GSC_REFRESH_TOKEN | | Stateless OAuth | | GSC_SERVICE_ACCOUNT_FILE, GSC_SERVICE_ACCOUNT_JSON | | Service account | | GSC_AUTH_MODE | auto | Force oauth, service_account or adc | | GSC_REPORT_LANGUAGE | en | Report language: en or it | | GSC_DATA_STATE | all | all includes today's partial data, final does not | | GSC_CACHE_TTL_SECONDS | 21600 | Response cache TTL; 0 disables it | | GSC_INSPECT_CONCURRENCY | 5 | Parallel URL inspections | | GSC_LOG_LEVEL | WARNING | Logging, always to stderr | | MCP_TRANSPORT, MCP_HOST, MCP_PORT | stdio | Transport |

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

uv venv && uv pip install -e ".[dev]"
ruff check src tests scripts && ruff format --check src tests scripts
pytest -q --cov=google_search_console_mcp
python scripts/sync_versions.py
python 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.

Related Skills

View on GitHub
GitHub Stars10
CategoryAutomation
Updated2d ago
Forks4

Languages

Python

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit โ€” see the Safety scan above for what the skill file itself contains.

1 info
google-search-console-mcp โ€” MCP Server: Install & Safety Check | SkillAgent