{
"markdown": "# google-search-console-mcp-server\n\n[](https://github.com/getmcpads-com/google-search-console-mcp-server/actions/workflows/ci.yml)\n[](LICENSE)\n[](package.json)\n\nAn open-source [Model Context Protocol](https://modelcontextprotocol.io) server for\n**Google Search Console**. It lets Claude, ChatGPT, Cursor or any MCP client query your\nsearch performance, inspect indexing, and analyse sitemaps.\n\n**Read-only, with no way to turn that off.** You run it, and your credentials stay on your\nmachine.\n\n```bash\nnpx -y @getmcpads/google-search-console-mcp-server\n```\n\nAlso listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as **`com.getmcpads/google-search-console`**, so clients that read the registry can install it by name.\n\n> **Prefer not to run it yourself?** [getmcpads.com](https://www.getmcpads.com) is the hosted\n> version of this server, with Search Console alongside Meta Ads, Google Ads, TikTok Ads,\n> Pinterest Ads and Google Analytics behind a single endpoint, hosted OAuth, and\n> cross-platform reporting. Same tools, same safety model, no setup.\n\n---\n\n## What you get\n\n| | |\n|---|---|\n| **20 read tools** | Search Analytics, sites, sitemaps, URL Inspection, and analyses built on top of them |\n| **SEO analyses, not just an API wrapper** | Cannibalisation detection, query clustering, wins and losses between periods, indexation watchlists, large-site sampling plans |\n| **7 resources** | Live catalogues the model can read: metrics, dimensions, filters, compatibility rules, 8 workflow recipes, read-only playbooks |\n| **Quota guardrails** | Every URL Inspection call is capped at 10 URLs, so one exploratory question cannot burn a day of quota |\n| **No writes at all** | Not a flag, a property of the code. See below |\n\n### What it does beyond fetching rows\n\nSearch Console answers questions about rows. Most real questions are about **change**: which\nqueries did we lose, which pages compete for the same term, is indexing drifting.\n\nThese tools do that work rather than leaving it to the model:\n\n| Tool | Question it answers |\n|---|---|\n| `gsc_detect_cannibalization` | Which pages compete for the same query |\n| `gsc_find_losses_gains` | What we won and lost between two periods |\n| `gsc_cluster_queries` | Which queries belong to the same intent |\n| `gsc_compare_search_types` | How web, image, video and news differ |\n| `gsc_analyze_search_appearance_trends` | How rich results evolve |\n| `gsc_indexation_watchlist` | Which URLs changed indexing verdict |\n| `gsc_plan_large_site_sampling` | Which URLs to inspect, when you cannot inspect them all |\n\n---\n\n## One thing to know before you trust a number\n\n**Search Console returns a top N, not a site total.**\n\nWhen you query with a dimension such as `query` or `page`, the API returns the highest\nranked rows up to your row limit, ordered by clicks. Summing the clicks of those rows does\n**not** give you the site total: the long tail is missing, and on a large site it can be most\nof the traffic.\n\nTo get a real total, query **without dimensions**. To compare periods, compare like with\nlike: same dimensions, same row limit, same search type.\n\n`gsc_query_search_analytics` reports what it actually returned, and `gsc_validate_query`\nchecks a combination before it runs. But the arithmetic mistake is yours to avoid, and it is\nthe most common one in Search Console analysis.\n\nTwo other limits worth carrying in your head:\n\n- **Roughly 16 months of history.** Anything older is gone, not slow.\n- **Data settles over about three days.** `gsc_get_data_freshness` tells you what is final.\n\n---\n\n## Read-only, and why it stays that way\n\nThere are no write tools, and no environment variable that adds any. The Search Console API\ncan submit and delete sitemaps, add and remove properties, and request indexing. **This\nserver exposes none of that.**\n\nThe scope it asks for reflects that: `webmasters.readonly`, not `webmasters`. Even if the\nmodel tried, the token cannot write.\n\nOur ad platform servers, where writes make sense, do have them, guarded by a mandatory\npreview:\n[Meta Ads](https://github.com/getmcpads-com/meta-ads-mcp-server) ·\n[Google Ads](https://github.com/getmcpads-com/google-ads-mcp-server) ·\n[TikTok Ads](https://github.com/getmcpads-com/tiktok-ads-mcp-server)\n\nThe hosted version at [getmcpads.com](https://www.getmcpads.com) keeps the same rule: Search\nConsole stays read-only there too.\n\n---\n\n## Getting credentials\n\nThree values, obtained once.\n\n### 1. OAuth client\n\nIn a [Google Cloud project](https://console.cloud.google.com/), enable the **Google Search\nConsole API**, then create an OAuth client under **APIs & Services → Credentials**. Choose\n**Desktop app** for local use. Note the **client ID** and **client secret**.\n\n### 2. Refresh token\n\nRun the OAuth consent flow once, signed in as a Google account that owns or can read your\nproperties, and keep the **refresh token**. Request `webmasters.readonly` and nothing more.\n\n📖 [Google OAuth for installed apps](https://developers.google.com/identity/protocols/oauth2/native-app)\n\n**The refresh token does not expire.** Use an OAuth client dedicated to this server so you\ncan revoke it on its own.\n\nFor a quick trial you can set `GSC_ACCESS_TOKEN` to a short-lived token instead, but it\nexpires within the hour and is useless for daily work.\n\nIf setting up an OAuth client is more than you want to do for one property,\n[getmcpads.com](https://www.getmcpads.com) handles the consent flow for you and gives you the\nsame tools behind a hosted endpoint.\n\n### 3. Site URL, optional\n\nSet `GSC_SITE_URL` to avoid passing it on every call. Both property forms work:\n\n| Property type | Value |\n|---|---|\n| URL-prefix | `https://example.com/` (the trailing slash matters) |\n| Domain | `sc-domain:example.com` |\n\nList what you can reach with `gsc_list_sites`, and run **`gsc_health_check`** as your first\ncall. It verifies the credentials without printing any secret.\n\n---\n\n## Setup\n\n### Claude Desktop\n\n`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\nor `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"search-console\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@getmcpads/google-search-console-mcp-server\"],\n \"env\": {\n \"GSC_CLIENT_ID\": \"your-client-id\",\n \"GSC_CLIENT_SECRET\": \"your-client-secret\",\n \"GSC_REFRESH_TOKEN\": \"your-refresh-token\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop. Ask it: *\"which queries did we lose last month?\"*.\n\n### Claude Code\n\n```bash\nclaude mcp add search-console --env GSC_CLIENT_ID=... --env GSC_CLIENT_SECRET=... --env GSC_REFRESH_TOKEN=... -- npx -y @getmcpads/google-search-console-mcp-server\n```\n\n### Cursor\n\n`.cursor/mcp.json` in your project, same shape as the Claude Desktop config above.\n\n### From source\n\n```bash\ngit clone https://github.com/getmcpads-com/google-search-console-mcp-server.git\ncd google-search-console-mcp-server\nnpm install && npm run build\ncp .env.example .env # then fill in your credentials\nnpm start\n```\n\n### Configuration\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `GSC_CLIENT_ID` | none | OAuth client ID |\n| `GSC_CLIENT_SECRET` | none | OAuth client secret |\n| `GSC_REFRESH_TOKEN` | none | From the consent flow |\n| `GSC_ACCESS_TOKEN` | none | Alternative to the three above, expires within the hour |\n| `GSC_SITE_URL` | none | Optional default property |\n| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |\n\nEither the three OAuth values, or `GSC_ACCESS_TOKEN`. The server refuses to start with neither.\n\n```bash\nnpm run doctor\n```\n\n---\n\n## Tools\n\n\n20 read tools
\n\n### Discovery and health\n| Tool | Purpose |\n|---|---|\n| `gsc_health_check` | Validates credentials and reachable properties |\n| `gsc_list_sites` / `gsc_get_site` | Properties you can reach, and their permission level |\n| `gsc_get_data_freshness` | How settled the most recent data is |\n\n### Search Analytics\n| Tool | Purpose |\n|---|---|\n| `gsc_query_search_analytics` | The main reporting tool. Dimensions, filters, date ranges |\n| `gsc_validate_query` | Check a combination *before* running it |\n| `gsc_compare_search_types` | Web, image, video, news and discover side by side |\n| `gsc_analyze_search_appearance_trends` | How rich results evolve over time |\n\n### SEO analysis\n| Tool | Purpose |\n|---|---|\n| `gsc_detect_cannibalization` | Pages competing for the same query |\n| `gsc_find_losses_gains` | Queries and pages won or lost between two periods |\n| `gsc_cluster_queries` | Group queries by shared intent |\n\n### Indexing\n| Tool | Purpose |\n|---|---|\n| `gsc_inspect_url` | Crawl and index status for one URL |\n| `gsc_bulk_inspect_urls` | Up to 10 URLs per call, to protect your quota |\n| `gsc_indexation_watchlist` | Track URLs whose verdict changed |\n| `gsc_monitor_indexation_freshness` | Freshness and indexation drift together |\n| `gsc_plan_large_site_sampling` | Build an inspection sample when you cannot inspect everything |\n\n### Sitemaps\n| Tool | Purpose |\n|---|---|\n| `gsc_list_sitemaps` / `gsc_get_sitemap` | Submitted sitemaps and their status |\n| `gsc_get_sitemap_health` | Errors, warnings and pending states |\n| `gsc_track_sitemap_deltas` | What changed against a baseline you supply |\n\n \n\n\n7 resources
\n\n| URI | Contents |\n|---|---|\n| `gsc://manifest` | What this server exposes, and which tool to run first |\n| `gsc://metrics` | The 8 Search Analytics metrics, raw and derived |\n| `gsc://dimensions` | The 7 dimensions and where they are valid |\n| `gsc://filters` | The 5 filter operators and their accepted values |\n| `gsc://compatibility` | Which dimensions work with which search types and data states |\n| `gsc://recipes` | 8 step-by-step workflows |\n| `gsc://p2-readonly-playbooks` | Monitoring playbooks and their invariants |\n\n \n\n---\n\n## Security\n\n- **The client secret and refresh token are never logged**, at any log level, or written to disk.\n- **Four hosts are contacted, and only four**: `searchconsole.googleapis.com` and\n `www.googleapis.com` for the API, `oauth2.googleapis.com` and `accounts.google.com` for\n OAuth. *A test fails the build if a fifth host appears in the source.*\n- **No fetch follows a redirect.** Every outbound call sets `redirect: \"error\"`, so a redirect\n cannot forward a bearer token or client secret to another host. *A test fails the build if\n any fetch omits this.*\n- **The scope is `webmasters.readonly`.** The token itself cannot write.\n- **No telemetry.** The server makes no network call other than to Google.\n\nFull policy: [SECURITY.md](SECURITY.md).\n\n---\n\n## Looking for a managed, multi-platform version?\n\nThis server does one platform, on your machine, with your credentials. That is on purpose.\n\nIf you'd rather not run it yourself, or you need Search Console **alongside Meta Ads, Google\nAds, TikTok Ads, Pinterest Ads and Google Analytics** behind one endpoint, with hosted OAuth\nand cross-platform reporting, that's what we build at **[getmcpads.com](https://www.getmcpads.com)**.\n\nSame philosophy, less plumbing. This project stays open source and independently useful\neither way.\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\nPlease read [SECURITY.md](SECURITY.md) before reporting anything security-related.\n\n## Licence\n\n[Apache License 2.0](LICENSE). See also [NOTICE](NOTICE).\n\nGoogle and Google Search Console are trademarks of Google LLC.\n**This project is not affiliated with, endorsed by, or sponsored by Google LLC.**\nIt is an independent client of a public API.\n",
"bytes": 11851,
"sha": "1406d3e30fa6b3e393eb9fae09615f28953cd68ca745c341fb10769ae99ac635",
"repo_slug": "getmcpads-com/google-search-console-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_com_getmcpads_google_search_console_621a7c3d/readme"
}