{
  "markdown": "<!-- mcp-name: io.github.acamolese/google-search-console-mcp -->\n\n# Google Search Console MCP\n\n**English** · [Italiano](README.it.md)\n\n[![CI](https://github.com/acamolese/google-search-console-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/acamolese/google-search-console-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/mcp-google-search-console)](https://pypi.org/project/mcp-google-search-console/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-google-search-console)](https://pypi.org/project/mcp-google-search-console/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\nSeventeen read-only tools over the Google Search Console API, plus a deterministic\nwhite-label HTML audit report an agency can put its own name on and send to a\nclient, in English or Italian.\n\n![The generated audit report](docs/report-preview.png)\n\nRegenerate that report from committed synthetic data, with no credentials:\n\n```bash\npython scripts/render_sample_report.py --lang en --open\n```\n\n## Install\n\n### Claude Code\n\n```bash\n/plugin marketplace add acamolese/google-search-console-mcp\n/plugin install google-search-console@acamolese\n```\n\nThe plugin brings the MCP server, five skills (weekly review, cannibalisation\ncheck, indexing audit, content opportunities, white-label client audit) and a\nconfig prompt for the three credentials.\n\n### Claude Desktop\n\nDownload `google-search-console.mcpb` from the\n[latest release](https://github.com/acamolese/google-search-console-mcp/releases)\nand open it. It needs [uv](https://docs.astral.sh/uv/) installed. Or edit the\nconfig file directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-search-console\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-google-search-console\"],\n      \"env\": {\n        \"GSC_CLIENT_ID\": \"...\",\n        \"GSC_CLIENT_SECRET\": \"...\",\n        \"GSC_REFRESH_TOKEN\": \"...\"\n      }\n    }\n  }\n}\n```\n\n### Cursor, Codex, Gemini CLI, Zed\n\nAny MCP client takes the same three lines: command `uvx`, argument\n`mcp-google-search-console`, and the three `GSC_*` environment variables.\n\n```bash\n# Codex\ncodex mcp add google-search-console -- uvx mcp-google-search-console\n\n# Gemini CLI\ngemini mcp add google-search-console uvx mcp-google-search-console\n```\n\n### Docker\n\n```bash\ndocker build -t mcp-gsc .\ndocker run --rm -p 127.0.0.1:8765:8765 \\\n  -e GSC_CLIENT_ID -e GSC_CLIENT_SECRET -e GSC_REFRESH_TOKEN \\\n  -v \"$PWD/reports:/reports\" mcp-gsc\n```\n\nThe container speaks streamable HTTP on `/mcp`. It has no authentication of its\nown: keep it on loopback or behind a reverse proxy.\n\n## Authentication\n\nThe OAuth scope is `webmasters.readonly` and nothing else. No tool in this server\ncan modify a property, a sitemap or anything else in Search Console.\n\nCredentials are resolved in this order:\n\n1. `GSC_AUTH_MODE` if set (`oauth`, `service_account`, `adc`)\n2. `GSC_SERVICE_ACCOUNT_FILE` or `GSC_SERVICE_ACCOUNT_JSON`\n3. `GSC_CLIENT_ID` + `GSC_CLIENT_SECRET` + `GSC_REFRESH_TOKEN`\n4. A token file in `~/.config/mcp-google-search-console/`\n5. Application Default Credentials\n\n### OAuth, once\n\n1. In [Google Cloud Console](https://console.cloud.google.com/), enable the\n   **Google Search Console API** and create an OAuth client of type\n   **Desktop app**.\n2. Export the client, or save the downloaded JSON as\n   `~/.config/mcp-google-search-console/oauth_credentials.json`:\n\n   ```bash\n   export GSC_CLIENT_ID=\"...apps.googleusercontent.com\"\n   export GSC_CLIENT_SECRET=\"...\"\n   uvx mcp-google-search-console auth\n   ```\n\n3. The browser flow prints the three `export` lines for a stateless setup, and\n   also stores a token at `~/.config/mcp-google-search-console/token.json` with\n   `0600` permissions.\n\nOn a headless machine, run `auth` on your laptop and copy the three environment\nvariables across. `--no-browser` prints the URL instead of opening one, but still\nneeds a local redirect.\n\n### Service account\n\nGrant the service account's email read access to the property in Search Console,\nthen point the server at the key:\n\n```bash\nexport GSC_SERVICE_ACCOUNT_FILE=/path/to/key.json\n# or, for a container:\nexport GSC_SERVICE_ACCOUNT_JSON='{\"type\":\"service_account\",...}'\n```\n\n### Check it works\n\n```bash\nuvx mcp-google-search-console doctor\n```\n\nPrints the auth mode in use, when the token expires, how many properties the\naccount can read, and the defaults every tool applies. Secrets are masked. Exits\n1 when nothing resolves, which is the answer to most \"the server won't start\"\nreports.\n\n## Tools\n\n| Tool | What it answers |\n|---|---|\n| `gsc_sites` | Which properties can this account read, and in what exact format |\n| `gsc_site_details` | Permission level and type for one property |\n| `gsc_query` | The Search Analytics report, with filters, dimensions and pagination |\n| `gsc_performance_overview` | Is the site up or down, against the previous period |\n| `gsc_compare_periods` | What changed between two periods, ranked by click delta |\n| `gsc_quick_wins` | Queries close enough to the top that a push would pay off |\n| `gsc_ctr_gaps` | Pages that rank but are not clicked |\n| `gsc_cannibalization` | Queries where several pages compete against each other |\n| `gsc_traffic_drops` | Pages that lost clicks, with a likely cause for each |\n| `gsc_content_decay` | Pages sliding down month after month |\n| `gsc_alerts` | What moved sharply enough to be worth a message today |\n| `gsc_portfolio` | Every property at a glance, worst first |\n| `gsc_indexing_issues` | Which of these URLs are indexed, and why not |\n| `gsc_inspect_url` | Full URL Inspection for one page |\n| `gsc_sitemaps` | Which sitemaps Google knows about, with errors and warnings |\n| `gsc_doctor` | What is configured, and does the API answer |\n| `gsc_audit` | The full HTML report |\n\nThree prompts wrap the workflows that repeat: `gsc_weekly_report`,\n`gsc_indexing_audit`, `gsc_content_opportunities`.\n\n## Why this server\n\n| | Here | Typical GSC MCP server |\n|---|---|---|\n| Client-ready report | Self-contained HTML, English or Italian, white-label | none |\n| Analysis | Cannibalisation, CTR gaps, decay, drop diagnosis, run server-side | raw rows, analysed by the model |\n| Thresholds | Adapt to the size of the property | fixed, or none |\n| Dates | `period=\"last_month\"`, `days=28`, resolved server-side | explicit dates only |\n| Freshness | `dataState=all` by default, matching the UI | `final` only |\n| Auth | OAuth, service account, ADC | OAuth only |\n| Output | TSV by default, roughly a third of the tokens of pretty JSON | `json.dumps(indent=2)` |\n| Errors | Google's reason plus what to do about it | bare HTTP status |\n| Tests | 280+, on both `mcp` majors, three operating systems | usually none |\n\n## Report customisation\n\nColours, logo, report name, brand terms and thresholds come from a JSON file.\nPass `branding_path`, or place it at\n`~/.config/mcp-google-search-console/branding.json` to apply it everywhere:\n\n```json\n{\n  \"brand_name\": \"Your Agency\",\n  \"logo\": \"logo.png\",\n  \"brand_terms\": [\"clientbrand\", \"client brand\"],\n  \"colors\": { \"primary\": \"#2b6cb0\", \"primary_dark\": \"#1a365d\" },\n  \"thresholds\": { \"min_impressions\": 200 }\n}\n```\n\nA local logo is base64-encoded into the document. A remote one is only kept if\n`allow_external_fonts` is true, because the report is otherwise guaranteed to\ncontain no external URL at all: no CDN, no font service, nothing that phones home\nwhen a client opens it.\n\n`brand_terms` matters more than it looks. Without it, the first label of the\ndomain is used as the brand, which is wrong for abbreviations, holding companies\nand invented names, and it silently mislabels the brand/non-brand split. The\nreport says when it had to guess.\n\n## Quotas and limits\n\n- **16 months** of daily data. Anything older is not available at any price.\n- **Hourly data**: the last 10 days only.\n- **URL Inspection**: 600 per minute and **2,000 per day per property**. This is\n  the limit that bites on a large site.\n- **Search Analytics**: 1,200 queries per minute per site. Responses are cached\n  in memory for 6 hours (1 hour for inspections); `no_cache=true` bypasses it.\n- **Rows**: 25,000 per API call. Tools default to 100 and cap at 1,000, with\n  `start_row` for pagination; the cap is reported in the response, never applied\n  silently.\n\n## Environment variables\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `GSC_CLIENT_ID`, `GSC_CLIENT_SECRET`, `GSC_REFRESH_TOKEN` | | Stateless OAuth |\n| `GSC_SERVICE_ACCOUNT_FILE`, `GSC_SERVICE_ACCOUNT_JSON` | | Service account |\n| `GSC_AUTH_MODE` | auto | Force `oauth`, `service_account` or `adc` |\n| `GSC_REPORT_LANGUAGE` | `en` | Report language: `en` or `it` |\n| `GSC_DATA_STATE` | `all` | `all` includes today's partial data, `final` does not |\n| `GSC_CACHE_TTL_SECONDS` | `21600` | Response cache TTL; `0` disables it |\n| `GSC_INSPECT_CONCURRENCY` | `5` | Parallel URL inspections |\n| `GSC_LOG_LEVEL` | `WARNING` | Logging, always to stderr |\n| `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT` | `stdio` | Transport |\n\n## Troubleshooting\n\n**`spawn uvx ENOENT`** — the client cannot find `uvx` on its PATH. GUI apps do\nnot inherit a shell PATH. Use the absolute path: `which uvx` gives it, typically\n`/Users/you/.local/bin/uvx`.\n\n**`403 forbidden` on every call** — almost always the property format. A domain\nproperty is `sc-domain:example.com`; a URL-prefix property is\n`https://example.com/`, trailing slash included. `gsc_sites` returns the exact\nstrings.\n\n**`401 invalid_grant`** — the refresh token was revoked or expired. Google expires\nrefresh tokens for OAuth apps still in \"testing\" after seven days; publish the\napp, or re-run `auth`.\n\n**`403 quotaExceeded`** — the daily URL Inspection quota is gone. It resets\ntomorrow; nothing retries past it.\n\n**Empty report on a small site** — check the thresholds in the response meta. They\nadapt to the property, but the floors (50 impressions, 10 clicks) still apply.\nPass `thresholds` to lower them.\n\n**Anything else** — run `doctor` and include its output in the issue.\n\n## Security\n\n- Read-only scope, requested and never widened.\n- Token files are written atomically with `0600` permissions. Credentials supplied\n  through the environment are never written to disk.\n- `gsc_doctor` masks the client ID and never returns a token.\n- No telemetry, no analytics, no request to any host other than Google's API.\n\nSee [SECURITY.md](SECURITY.md) for the reporting policy.\n\n## Development\n\n```bash\nuv venv && uv pip install -e \".[dev]\"\nruff check src tests scripts && ruff format --check src tests scripts\npytest -q --cov=google_search_console_mcp\npython scripts/sync_versions.py\npython scripts/render_sample_report.py --lang it --open\n```\n\nTests never hit the network. Live tests exist behind `-m live` and require\n`GSC_LIVE_TESTS=1` plus credentials; they never run in CI.\n\nReleases: see [docs/RELEASING.md](docs/RELEASING.md). Decisions not covered by the\ncode are logged in [docs/DECISIONS.md](docs/DECISIONS.md).\n\n## License\n\nMIT. Chart.js 4.5.1 is vendored under `src/google_search_console_mcp/static/`,\nalso MIT, with its licence alongside.\n",
  "bytes": 11050,
  "sha": "03c4d6255976d91d21db8abeae4417094505337a89f0e60e23a6d7870d5cfda8",
  "repo_slug": "acamolese/google-search-console-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_acamolese_google_search_consol_803c197e/readme"
}