Google Search Console MCP

English · Italiano

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.

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

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

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

Why this server

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

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.