Google Search Console MCP
This MCP server connects an AI client to Google Search Console so it can analyze organic search performance, inspect indexing and sitemap health, and optionally make property, sitemap, or limited indexing changes.
Discover server capabilities and Google auth/access-mode status.
List Search Console properties and query clicks, impressions, CTR, and average position with dimensions, filters, pagination, and search-type options.
Compare performance across two date ranges and dimensions.
Inspect a URL’s Google index status, crawl signals, and related indexing details.
List and get sitemap status, warnings, errors, submission/download dates, and submitted URL counts.
Identify quick-win queries, keyword cannibalization, and content-decay pages.
List pages receiving search impressions as a performance proxy.
Generate a weekly performance digest in markdown.
In read-write mode, add/delete properties, submit/delete sitemaps, and request indexing for eligible JobPosting or livestream URLs.
Provides tools for interacting with Google Search Console, enabling AI agents to query search analytics (impressions, clicks, CTR, position), inspect URLs, manage sitemaps, list sites, and identify SEO opportunities such as quick wins, content decay, and keyword cannibalization.
mcp-gsc
Part of the DigestSEO suite of open-source SEO tools.
Product: digestseo.com/gsc-mcp
Engineering case study: DigestSEO MCP Suite — AI visibility, Search Console, web validation, and trend intelligence
Support: digestseo.com/support
Privacy: digestseo.com/privacy
The self-hosting launcher is available as @digestseo/mcp-gsc. For new analytics/reporting-only connections, explicitly start in read-only mode:
GSC_ACCESS_MODE=readonly npx -y @digestseo/mcp-gscOn Windows PowerShell, use $env:GSC_ACCESS_MODE = 'readonly' followed by npx -y @digestseo/mcp-gsc instead. Supply your own Google OAuth and encryption settings from SETUP.md before starting either command.
The npm launcher starts a loopback-only Streamable HTTP Worker on 127.0.0.1 (port 8080 by default); it is not a stdio MCP process. You can run the npx command from any directory because the launcher resolves its bundled Worker configuration from the installed package. Clients that launch the package should connect to http://127.0.0.1:8080/mcp after supplying the Google OAuth and token-encryption environment variables described in SETUP.md. The launcher exits before starting Wrangler if GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, or TOKEN_ENCRYPTION_KEY is missing or blank, and it also rejects a nonblank TOKEN_ENCRYPTION_KEY unless it is valid base64 that decodes to exactly 32 bytes. Errors identify only the invalid or missing setting, never its secret value, so a broken OAuth session is not started. It keeps secret values in the child process environment and Wrangler loads them through declared local secrets; their values are not copied into Wrangler --var command-line arguments. Before the first OAuth sign-in, authorize the exact callback http://127.0.0.1:8080/google/callback in Google Cloud (or use the same custom PORT you launch with); the launcher prints both URLs at startup.
Docker/Glama network binding. The ordinary npx launcher stays loopback-only by default (MCP_GSC_BIND_IP=127.0.0.1). The Docker image explicitly sets MCP_GSC_BIND_IP=0.0.0.0 inside the container, because Docker port forwarding cannot reach a service bound only to the container's loopback interface. When publishing a Docker port on your computer, prefer -p 127.0.0.1:8080:8080 to restrict host access; expose it beyond the host only with appropriate HTTPS/OAuth deployment configuration and an authorized Google redirect URI. MCP_GSC_BIND_IP accepts only 127.0.0.1 or 0.0.0.0; do not use all-interface binding for ordinary local npm usage.
Local KV and Durable Object state, including the encrypted Google session, is stored in ~/.mcp-gsc/state by default instead of inside the versioned npm cache. That keeps the local connection available across package upgrades and ordinary npm cache cleanup. Set MCP_GSC_STATE_DIR to use another directory; keep the same TOKEN_ENCRYPTION_KEY when reusing existing state because stored refresh tokens are encrypted with that key. The launcher prints the effective state directory at startup. The first release with this stable path may require one Google reconnect because older launcher releases stored local state under the npm package cache.
The launcher's implicit fallback remains GSC_ACCESS_MODE=readwrite for backward compatibility. The read-only commands above and checked-in self-hosting templates explicitly select readonly: Google OAuth then requests only the read-only Search Console scope, and the six mutation tools stay unregistered. Opt into readwrite only for workflows that actually require changes to Search Console properties, sitemaps or eligible Indexing API URLs.
For Google OAuth and Cloudflare deployment configuration, follow SETUP.md.
Connect the local launcher
For the current verified quick-connect path, supply the Google OAuth and token-encryption environment variables described in SETUP.md, then start the npm launcher using the appropriate read-only command above (or deliberately choose readwrite for a privileged workflow).
Then connect your MCP client to the launcher's loopback endpoint:
http://127.0.0.1:8080/mcpSelf-hosted Cloudflare Worker deployments continue to use https://<your-worker>.workers.dev/mcp. The repo does not currently advertise the owner-hosted remote as a quick-connect path because its deployed tool contract is behind the published package.
Claude Code
claude mcp add --transport http gsc http://127.0.0.1:8080/mcpOpenAI Codex CLI / IDE
codex mcp add gsc --url http://127.0.0.1:8080/mcpCodex CLI and the Codex IDE extension share MCP configuration, so registering the server once makes the same local connection available to both clients. Start the npm launcher before using the connection; Codex will open the server's OAuth flow when authentication is required.
Visual Studio Code (GitHub Copilot)
The button adds only the local Streamable HTTP connection; it does not start the npm launcher or configure Google OAuth. Follow SETUP.md and start the launcher above on the same machine as VS Code before connecting and signing in. Remote VS Code environments cannot reach your computer's 127.0.0.1 endpoint.
Cursor
When this repository is installed as a Cursor plugin, Cursor also auto-discovers three bundled Agent Skills that compose the MCP tools into evidence-safe workflows: gsc-weekly-review, gsc-indexing-triage, and gsc-search-opportunities. The Add to Cursor button above installs the MCP connection only; the bundled skills are part of the repository's Cursor plugin package.
The button and plugin MCP configuration above are for Cursor running on the same machine as the npm launcher. Cursor Cloud Agents run in isolated cloud VMs, so they cannot reach 127.0.0.1 on your computer. For Cloud Agents, deploy your own externally reachable HTTPS Worker and add its /mcp URL from the MCP controls at cursor.com/agents; Cursor supports HTTP MCP servers and OAuth there. Do not reuse the loopback URL for a Cloud Agent.
GitHub Copilot CLI
copilot plugin marketplace add AKzar1el/mcp-gsc
copilot plugin install mcp-gsc@digestseoThe marketplace path makes the plugin discoverable and updateable through Copilot's marketplace workflow. Direct repository install also remains supported with copilot plugin install AKzar1el/mcp-gsc. The Copilot plugin bundles the same three Agent Skills plus the local loopback MCP configuration. Start the npm launcher before using the plugin's MCP server; the plugin does not start or deploy mcp-gsc for you.
Gemini CLI
gemini extensions install https://github.com/AKzar1el/mcp-gscThe Gemini CLI extension bundles the verified local loopback MCP configuration plus the same three Agent Skills: gsc-weekly-review, gsc-indexing-triage, and gsc-search-opportunities. Start the npm launcher before using the extension; the extension does not start or deploy mcp-gsc for you.
Kiro
Start the npm launcher before using either install button or the Copilot plugin. Complete its Google OAuth flow on first use.
ChatGPT — ChatGPT cannot connect directly to this loopback 127.0.0.1 endpoint. For private/local use, create an OpenAI Secure MCP Tunnel, then run tunnel-client on the same machine as the launcher so it can reach http://127.0.0.1:8080/mcp; when creating the ChatGPT app, choose the Tunnel connection and select that tunnel. The tunnel setup requires an OpenAI tunnel_id and runtime API key; see OpenAI's Secure MCP Tunnel guide. The tunnel keeps the MCP server private and is intended for private/developer-mode connectivity, not public plugin distribution.
Alternatively, deploy your own remote Cloudflare Worker and add its HTTPS /mcp URL as a custom MCP app in Developer mode; see Connect in your AI client below.
A self-hostable Model Context Protocol (MCP) server for Google Search Console. Connect it to Claude.ai, Cursor, ChatGPT, or any MCP-compatible client and ask your AI assistant about your site's organic search performance — impressions, clicks, top queries, index status, and sitemap health — straight from your own Google account.
It runs on Cloudflare Workers and ships with Google OAuth onboarding: connect the server in your client, review the mcp-gsc consent page that identifies the requesting MCP client and permissions, then sign in with Google and grant the requested Google Search Console permissions. No API keys to copy around and no service-account JSON to manage.
Tools
By default (GSC_ACCESS_MODE=readwrite), this server exposes 23 tools. Read-only analytics and reporting tools are marked with MCP's readOnlyHint; the write tools below can change Search Console properties, sitemaps, or indexing state. Set GSC_ACCESS_MODE=readonly to request only the Search Console read-only scope and expose the 16 tools that do not require either write access or the separate Indexing API scope.
Tool | Access | What it does |
| Read | List every tool this server exposes and report local Google credential state. |
| Read | List the Search Console properties the connected Google account can access ( |
| Read | Retrieve one exact Search Console property and the connected account's permission level for it. |
| Read | Impressions, clicks, CTR, and average position over a date range, with dimensions, filters, safe pagination, and selectable search type. Pass |
For regional or cross-device Search Analytics without stitching together separate provider requests, use dimension_filter_groups: [{ "filterLists": [{ "dimension": "country", "expressions": ["DEU", "AUT", "CHE"] }, { "dimension": "device", "expressions": ["MOBILE", "DESKTOP"] }] }] with analytics.query or analytics.compare. Google matches any value within each list and all selected dimensions, so this example means a DACH searcher country and mobile/desktop. The MCP normalizes case, accepts 1-50 exact values per list, and rejects invalid/duplicate values and mixing filters with filterLists on the same dimension (including across groups). Omitting both filter types retains unfiltered behavior. Lists do not add API calls, alter the normal quota, override property permissions, or make returned rows exhaustive; country is the searcher's location, not a URL locale. Requires Google Search Analytics API support announced November 16, 2026.
| insights.page_queries / insights.query_pages | Read | Drill from one exact page to its Search Console queries, or from one exact query to the pages Google surfaced for it, with row_limit / start_row pagination. insights.page_queries accepts query_contains to narrow query topics; insights.query_pages accepts page_contains to narrow URLs. Both accept optional singular country (ISO alpha-3 searcher geography, not page language) and device (desktop/mobile/tablet), or plural countries (1-10 distinct ISO alpha-3) and devices (1-3 distinct desktop/mobile/tablet); never mix singular and plural within one dimension. Lists apply Google-side OR within a dimension and AND across dimensions, exact page/query, and optional substring in one request. Combined results are not per-country/device attribution, and missing or paginated rows do not imply zero traffic or an exhaustive dataset. Web, image, video and Search results News tab are supported; Discover and the separate Google News report lack query data. |
| urls.inspect | Read | Google's URL Inspection report for the version of one page currently known in Google's index. It is not a live URL test; mobile-usability output is deprecated. |
| urls.inspect_many | Read | Inspect Google's indexed versions of up to 10 URLs sequentially in one call while preserving input-order results. index_status_counts summarizes indexed, not-indexed and unknown states among successful inspections only; failed requests are separate, and this is not site-wide coverage. Each URL still consumes one Google URL Inspection request and one unit of the server's shared inspection safety budget; this does not run live URL tests. |
| sitemaps.list / sitemaps.get | Read | List submitted sitemaps or retrieve one sitemap's details. lastSubmitted is when the sitemap was submitted to Search Console; lastDownloaded is when Google last downloaded the sitemap. Neither value is the sitemap file's modification/deploy time or a page crawl/indexing timestamp. |
| insights.quick_wins / insights.cannibalization / insights.content_decay | Read | Surface average-position opportunity rows, query/page overlap, and evidence-ranked click declines. Quick wins accepts optional page_contains (for example /de/), query_contains (for example technical seo) and country (for example DEU for searchers in Germany, not German-language pages). They combine as Google-side AND filters before pagination to find geographically and topically relevant opportunities without unrelated rows crowding the source window; filtered results are not property-wide. Quick-win candidates use aggregate Search Console average position, not a stable current rank, and optional max_ctr (a 0-1 fraction) limits candidates by observed CTR after Google pagination, without proving an SEO problem. Cannibalization accepts optional query_contains (for example pricing) and page_contains (for example /de/), combined as Google-side AND filters before source pagination; query scope retains all returned competing URLs for matching topics, while page scope limits observed shares to those URLs rather than property-wide totals. Candidate totals/shares derive from observed query/page rows rather than true query-level property totals. Content-decay accepts optional case-insensitive page_contains and query_contains across both Google requests, separately or combined as AND before pagination, to compare topic-specific page traffic (not sitewide totals) without extra API calls; it allows 1-240 days per comparison period to fit Search Console history. Content-decay results compare only pages returned in both periods and do not turn one-sided row absence into zero traffic. |
| indexing.list_pages / analytics.compare | Read | Analyze pages receiving Search Console impressions and compare two periods, optionally using the same search type and query/page/country/device/search-appearance filters for both periods. analytics.compare compares only dimension keys returned in both period responses and includes observed_dimension_overlap counts (each period, common and one-period-only) plus up to three one-period-only observed examples from each period, ranked by their returned impressions. These examples help choose follow-up checks, not prove a new or vanished query/page: absent keys in non-exhaustive Search Analytics responses are not zero traffic. It defaults to finalized Search Analytics rows with data_state=final, preserving Google's omitted-dataState behavior; pass all explicitly when recent preliminary-capable rows are desired. Discover (search_type: "discover") and Google News ("googleNews", not Search's News tab) can be compared by page, country, or device when that property has eligible data: average position and its change are null, never an inferred ranking, and query dimensions/filters are rejected before contacting Google. Each comparison uses the same bounded Search Analytics request path; switching surface adds no extra calls. indexing.list_pages is performance data, not index coverage: a missing URL may still be indexed; use urls.inspect / urls.inspect_many for URL-level index status. Its returned pages retain observed clicks and impressions when Google omits optional average position (position: null, never zero). |
| reports.weekly_digest | Read | Generate a plain-language seven-day performance report with movers, top pages, and evidence-based next steps. Finalized reports can highlight up to three directly returned zero-click query rows with positive impressions, ranked by observed impressions; this is an up-to-25-row, non-exhaustive sample, not proof of missing or anonymized query performance, and uses no extra API request. Optional search_type supports Web (default), Image, Video and the Google Search News tab, consistently applied to every request; Discover and the Google News app are excluded because they do not expose query rows. Non-Web reports explicitly label their search surface and avoid Web-specific content advice. Optional page_contains restricts matching URLs (such as /de/), device selects desktop, mobile or tablet, query_contains narrows a topic (such as technical seo), and country selects a searcher country by ISO 3166-1 alpha-3 code (such as SVN; not a page locale). All selected filters combine in one Google-side AND group across totals, queries and pages without adding requests. Topic-filtered reports exclude other and anonymized queries and are not property-wide totals; omit filters for unsegmented reporting. Query movers compare only rows returned in both weekly Search Analytics result sets; a query missing from one bounded response is not treated as zero because Google does not guarantee every data row. |
| sites.add / sites.delete | Write | Add or remove a property from the connected account's Search Console site set. sites.add returns ownership_verification_performed: false because ownership verification is a separate Google Site Verification/Search Console workflow. sites.delete removes the property from that account's Search Console site set; it does not delete the website itself. |
| sitemaps.submit / sitemaps.delete | Write | Submit or remove a sitemap. |
| indexing.status | Read | Read Google's latest successful Indexing API URL_UPDATED / URL_DELETED notification receipts for a previously submitted URL. This is notification metadata only, not index coverage, crawl status, indexing completion, or removal completion. It requires GSC_ACCESS_MODE=readwrite because Google's metadata endpoint uses the Indexing API OAuth scope. |
| indexing.request | Write | Requests indexing through Google's Indexing API. Google currently restricts this API to pages containing JobPosting structured data or livestream pages containing BroadcastEvent inside VideoObject. It is not available for general webpage submission. Google's documented default is 200 publish requests/day/project shared by updates and removals. Eligible content types, API authorization, quota limits and spam policies still apply; this quota is not permission to submit other page types or exceed Google's limits. |
| indexing.remove | Write | Request a URL_DELETED notification for a previously eligible Indexing API page. Before removal, the URL must already return HTTP 404/410 or expose a noindex meta directive addressed to robots or googlebot (not just googlebot-news). Google's receipt does not prove removal completed; use URL Inspection for indexed-state evidence. |
For aggregated regional weekly reports, reports.weekly_digest also accepts countries (1-10 distinct ISO alpha-3 codes) and devices (1-3 distinct device values) as arrays. Use the plural alternative instead of country or device for that dimension; never provide both forms. Values within a list are ORed by Google using filterLists; page, query, country, and device scopes remain ANDed across every request. A filtered report describes only the selected searchers, not all site traffic. The five finalized (or three preliminary) Search Analytics requests and existing shared quotas are unchanged. For an exact observed page or query, insights.page_queries and insights.query_pages preserve those same list scopes in one bounded read; analytics.query remains an alternative. Keep exact dates, search surface and filters in follow-ups.
Guided read-only investigation
Call server.capabilities to see the names and purposes of all existing guided read-only MCP prompts alongside the tool catalog, even when your client does not display a prompt picker. This is discovery metadata only: using a prompt still requires client support for prompts/list and prompts/get; listing it does not make an unsupported client able to run it. The catalog itself makes no Google API request, and following a prompt's suggested reads consumes the normal quotas.
New to a Search Console connection? gsc-property-readiness-review is a read-only MCP prompt that checks credential-state evidence and helps identify accessible exact property identifiers and permission levels using server.capabilities, sites.list, and an optional exact-property sites.get. It never silently chooses another property, changes access, or treats a stored refresh token as verified live Google access. Retrieving the prompt makes no Google request; any subsequently followed Google reads consume normal quota. Its availability depends on the MCP client's prompt support.
Investigating a sudden impressions or clicks collapse? Follow the read-only visibility incident playbook to choose the smallest useful sequence of existing daily-onset, traffic-drop, query/page, country and URL Inspection workflows while preserving property scope, finalized dates and quota safeguards. This guide makes no Google API requests by itself and does not claim an SEO cause or recovery.
For a focused optimization shortlist, gsc-quick-win-review accepts an exact Search Console property, inclusive Pacific dates, search surface and optional URL/query topic, device and searcher-country scopes. Both singular and list scopes now guide one bounded read-only insights.quick_wins review. For combined markets or devices, use countries (1-10 ISO alpha-3 codes) and/or devices (1-3 types) as comma/newline-separated or JSON-array strings, never alongside the matching singular field. The direct tool now supports Google-side filterLists for combined scopes without requiring a separate sampled analytics.query workaround. OR within each list and AND across dimensions returns one combined segment, not separately measured markets or devices. Candidates come from bounded, non-exhaustive Search Analytics rows: low CTR and aggregate average position do not establish a live ranking or guaranteed opportunity, and omitted rows are not zero. A justified query/page drilldown must preserve the exact scope. Retrieving this MCP prompt makes no Google request; following its suggested read tools consumes their normal quotas and never authorizes an indexing or content write. Availability depends on the MCP client's prompt support.
For an evidence-first check of queries appearing across multiple pages, gsc-query-overlap-review accepts an exact property, inclusive Pacific dates, search surface and optional query topic, URL section, searcher country and device. It guides a bounded read-only insights.cannibalization review with a justified optional insights.query_pages check. Multiple observed URLs are not proof of harmful cannibalization; URL-section filters exclude other competing pages, and impression shares are limited to the non-exhaustive returned sample, not property-wide totals. Retrieving the prompt makes no Google API request, and it never authorizes redirects, canonicals, indexing or content changes; subsequent read calls consume normal quotas. Client UI availability depends on MCP prompt support.
To investigate observed rich-result and Search appearance visibility, gsc-search-appearance-review accepts one exact property, optional Pacific end_date, web/image/video/Search News search_type, and optional ISO alpha-3 searcher country/device or alternative countries (1–10) and devices (1–3) lists. Pass list values as comma-separated or JSON-array text; do not combine a singular and plural field for one dimension. It guides two bounded, matched finalized-week analytics.query calls grouped by searchAppearance alone to discover actual provider-returned appearance types, plus at most one justified page-level query filtered to one exact observed type. Multi-value scopes use identical Google-side filterLists (OR within country/device lists, AND across dimensions) throughout discovery and drilldown; combined results are not per-country/device attribution. Appearance types can overlap; returned rows are incomplete samples, not exhaustive totals, schema validation results, or proof of indexing or ranking causality. Retrieving the prompt contacts no provider, and suggested read calls use the normal quota budget. Client support for MCP prompts varies.
For a concise weekly report that a client can review, gsc-weekly-client-report is an MCP-discoverable, read-only prompt with exact property, optional Pacific end_date, search surface, URL section, query topic, and searcher country/device. For a combined segment, it also accepts countries (1-10 ISO alpha-3 codes) and devices (1-3 device types) as comma/newline-separated or JSON-array strings over MCP; use either the singular or plural form per dimension, never both. The prompt passes plural filters as arrays to reports.weekly_digest, which uses Google-side OR lists and ANDs different dimensions without adding API requests. These results represent one combined segment, not individual country/device breakdowns or property-wide traffic. Follow-ups can use insights.page_queries or insights.query_pages with identical list filters and exact dates on a supported search surface, or a matching analytics.query. Do not treat analytics.compare as interchangeable or silently narrow a combined segment. Prompt retrieval makes no Google API request, while following its report steps uses normal read quotas. It creates a draft only: it does not send email, contact clients, publish, or guarantee SEO outcomes. Prompt availability in a client UI depends on that client's MCP prompt support.
Clients that support MCP prompts can discover gsc-traffic-drop-triage through prompts/list and retrieve it with prompts/get. Supply an exact Search Console site_url, optionally end_date (Pacific calendar), page_contains (for example /de/), search_type (web, image, video, or Google Search News-tab news), ISO alpha-3 searcher country (for example DEU) and device (desktop, mobile, tablet). Alternatively, use countries (1-10 ISO alpha-3 codes) and/or devices (1-3 types) as comma/newline-separated or JSON-array strings, never together with the singular form for the same dimension. Single-value triage guides the existing digest, content-decay, comparison and page drilldown tools. Multi-value triage instead guides two finalized seven-day analytics.query date reads with identical Google-side filterLists (OR within country/device lists, AND across dimensions), to locate possible daily onset; digest and content-decay tools now preserve the same list scopes for separate quota-bounded follow-ups, while direct page/query drilldowns also preserve them when an exact observed page or query merits another quota-bounded read. Missing dates are unknown, not measured zeros or complete-week totals; the combined segment is not a per-country/device breakdown. A bounded page-cohort follow-up can retain list scopes if independently authorized. Country is the searcher's location, not URL language; segmented results are not property-wide totals. Preliminary end dates cannot support finalized trend claims, and list-based triage rejects nonfinal end dates. Retrieving the prompt makes no Google API calls and does not modify a property; following the suggested calls consumes normal read quotas. The prompt is guidance, not a traffic-drop diagnosis or a guarantee that any MCP client exposes prompts in its UI.
For a more precise view of when a visibility decline became observable, gsc-daily-onset-review guides one read-only, date-grouped Search Analytics query across 21 finalized Pacific-calendar days. Supply an exact property and optionally a finalized end date, Search surface, URL section, single ISO alpha-3 searcher country/device, or the corresponding countries/devices lists (1-10 countries, 1-3 devices, comma/newline-separated or JSON-array strings). Lists use Google-side filterLists (OR within each list, AND across dimensions) for one combined segment, not separate measurements for each country or device. Do not combine single and list filters for the same dimension. The webMultimodal surface is available for Google Lens/Circle to Search date trends, not query-keyword analysis; it must not be added to ordinary Web or Image-tab results as if disjoint. It compares only returned dates (including same-weekday comparisons seven days apart), never converts missing dates to zero, and labels causal explanations and onset confidence as uncertain unless supported. The gsc-traffic-drop-triage prompt accepts the same country/device lists for Web, Image, Video and News-tab follow-ups; insights.page_queries and insights.query_pages preserve lists on their supported search surfaces with equal dates and filters. For webMultimodal, do not pass the unsupported surface to triage or silently relabel Lens traffic as Web/Image: recommend an independently authorized, same-scope read-only analytics.query instead. Retrieving the prompt makes no Google request; executing the suggested query consumes the normal read quota. It does not publish reports, modify index status or guarantee a diagnosis.
For a bounded look at which observed top queries changed, gsc-query-cohort-review compares two finalized seven-day Pacific windows with optional Google-side URL-section, query-topic, searcher-country and device filters. Choose a single country/device or the corresponding countries/devices list (1-10 ISO alpha-3 country codes, 1-3 lowercase devices), supplied as comma/newline-separated text or a JSON-array string in MCP clients. Country and device lists use Google's filterLists: OR within a list and AND across different dimensions and any page/query filters. For one exact observed query, insights.query_pages preserves the same lists and finalized period in a quota-bounded page drilldown; analytics.query remains an option with matching Google-side filters. Omitted pages are not zero. Measured changes are reported only for query keys seen in both returned samples; one-period-only keys are follow-up leads, not proven lost or new queries. Google's click-sorted Search Analytics results are incomplete; omitted rows are not measured zero. Prompt retrieval makes no Google request; two read calls and a justified optional page drilldown use normal quotas. Client support for MCP prompts varies.
For a quick first pass at which searcher countries changed, gsc-country-movement-review guides a single analytics.compare review of two adjacent, finalized seven-day windows, grouping by country. Supply the exact site_url and optionally a finalized Pacific end_date, search_type, URL-section page_contains (such as /de/) and device. The webMultimodal option compares searcher countries for image-initiated Lens/Circle to Search traffic without the unsupported text-query dimension. The workflow compares only countries observed in both bounded Search Analytics samples; missing rows are not measured zero, and observations are not an exhaustive country list. Searcher geography is not the page's language or locale; a /de/ URL-section filter does not mean German searchers. Retrieving the prompt makes no Google call, while its suggested comparison and optional justified drilldown use normal read quotas. It makes no changes, and client support for MCP prompts varies.
For a specific URL's index-status problem, gsc-index-status-triage accepts an exact site_url and one inspection_url within that property. It guides a read-only check of Google's indexed-state evidence, canonicals, crawl signals and optional sitemap context without offering general-purpose indexing submission. Prompt retrieval makes no Google request; an optional urls.inspect call consumes URL Inspection quota. Google URL Inspection is not a live URL test, sitemap timestamps do not prove indexing, and neither tool can guarantee that Google will index a page.
To compare a short list of important URLs, gsc-index-batch-review accepts one exact site_url and 2-10 unique inspection_urls within that same property. MCP prompts/get arguments are strings: supply inspection_urls as newline-separated URL text (for example https://example.com/a/\nhttps://example.com/b/, with an actual newline) or as a JSON-array string, not a raw JSON array. Prompt retrieval validates property boundaries without contacting Google. It guides a single ordered, sequential urls.inspect_many read only after checking access and available quota (20 URL inspections per user per day under this server's safety guard, with extra units for retries). Its per-URL results keep indexed, not_indexed, unknown, failed and omitted evidence distinct; index_status_counts covers successful inspections only, not all pages on the property. The prompt never submits indexing requests, performs a live URL test or guarantees an indexing outcome. MCP client support for prompts varies.
To triage submitted sitemap processing and warnings, gsc-sitemap-health-review accepts an exact Search Console site_url and optional HTTP(S) sitemap_index filter. It guides bounded, paginated, read-only sitemaps.list checks and at most one evidence-justified sitemaps.get drilldown. An authorized sitemap can be hosted on a different origin than the property; the filter is not restricted to the property's hostname. Reported errors, warnings, pending status and download/submission timestamps describe sitemap processing, not page indexing, and submitted URL counts are not indexed counts. The prompt makes no provider request when retrieved and never submits, deletes, publishes or changes a sitemap; its suggested read operations consume normal quotas and may be incomplete after a bounded page limit. Client MCP prompt support varies.
For insights.page_queries and insights.query_pages, optional data_state: "all" includes fresh, potentially preliminary Search Analytics rows when drilling from one page to its queries or one query to its pages. Omitting data_state preserves Google's finalized-only default (final). Both results report data_state and preliminary_data_possible so recently changing numbers are not mistaken for settled results. Their structured responses also identify the exact site_url, inclusive start_date/end_date, and search_type, so saved drilldowns retain their reporting context across properties, periods and search surfaces. Both directions retain returned clicks and impressions even when Google omits average position; in that case position is null, not a zero or live rank. These details do not add a Google request, alter filters, pagination or quotas, or imply exhaustive Search Analytics coverage.
For insights.quick_wins, optional device selects desktop, mobile, or tablet so that an opportunity found in a device-specific weekly digest can be investigated on the same device. It combines with page_contains, query_contains, and country as Google-side AND filters before pagination without additional API requests. Omitting device retains all-device behavior. Device-scoped candidates are observed rows, not property-wide or all-device totals.
For multi-market opportunity discovery, insights.quick_wins also accepts countries (1-10 distinct ISO alpha-3 searcher codes) and devices (1-3 distinct device types). Use each list instead of its singular country/device option; mixing forms or repeating values is rejected before a provider read. Google-side filterLists OR values within a dimension and AND them with URL/query filters and the other selected dimension. Results echo the combined segment and preserve the existing pagination, result bounds and read quotas; they do not provide separate per-market/device attribution, exhaustive source rows or guaranteed SEO gains.
For insights.cannibalization, returned query/page rows with measured clicks and impressions are retained even if Google omits optional average position: the affected page reports position: null, never a guessed rank or a measured zero. The candidate's observed impression shares include those rows; they remain a bounded sample, not proof of harmful cannibalization or complete query-level traffic. This adds no Google requests or quota units.
For insights.quick_wins, optional search_type selects web (default), image, video, or news (Google Search News tab, not the separate Google News service), so an Image or Video weekly report can lead to opportunity discovery on that same search surface. Impression thresholds and average positions are interpreted within the selected surface, not across all searches; results remain observed rows, never guaranteed exhaustive. Google Discover and Google News are excluded because this opportunity heuristic relies on average position. The selected type does not add another API request or change quota limits.
For insights.quick_wins, optional data_state: "all" includes fresh preliminary Search Analytics observations in opportunity discovery; these metrics and ranks may change before Google finalizes them. Omit it to retain the finalized-only default, or set "final" explicitly. Results identify the effective data_state and preliminary_data_possible; this option uses the same Google request and does not alter quotas or property authorization.
For insights.quick_wins, optional max_ctr: 0.02 selects only returned query/page opportunities with observed CTR at most 2%, in addition to the impression and average-position thresholds. The inclusive 0-to-1 fraction is echoed in max_ctr (null when omitted); max_ctr: 0 includes zero-click rows. This filter is applied locally after bounded Google pagination, not within the Google API request, and does not retrieve otherwise omitted rows or add quota usage. A low CTR alone is not proof that a title or page needs changing; review query intent and search features first.
For insights.content_decay, optional search_type selects web (default), image, video, or news (Google Search's News tab). The selected type applies to both periods and is echoed in the response so comparisons cannot accidentally mix surfaces. Discover and Google News are excluded because the decay heuristic requires average-position evidence that those reports do not provide; use analytics.query for their click/impression trends instead. This adds no extra Google requests or quota units.
For insights.content_decay, optional country scopes searcher location using a three-letter ISO 3166-1 alpha-3 code (for example DEU), not the language of the page. It can be combined with page_contains and query_contains in one Google-side AND filter applied identically to both comparison periods, without extra requests. A country-scoped decline is not a property-wide decline, and an absent page row in one period is not evidence of zero traffic.
For insights.content_decay, optional device selects desktop, mobile, or tablet to investigate declines within the same device segment as a weekly digest or quick-wins report. It combines with page_contains, query_contains, and country as Google-side AND filters across both periods without extra requests; omitting it retains all-device behavior. Device-scoped declines are not property-wide or all-device changes, and missing rows are never counted as zero.
For insights.content_decay, optional countries and devices accept 1-10 distinct ISO alpha-3 searcher countries and 1-3 distinct devices. Use either the plural list or the corresponding singular selector, never both; duplicate values are rejected. Google-side filterLists OR values within each dimension and AND the selected dimensions with page/query filters identically in both comparison periods. Responses echo the normalized list scope, not separate country/device attribution. The comparison still uses two normal Search Analytics reads and only assesses pages returned in both periods; absent rows are not measured zeros or evidence of deindexing.
For insights.content_decay, optional end_date anchors a historical comparison to a selected finalized Search Console date (YYYY-MM-DD, Pacific Time), such as the date before or after a site migration. The recent period ends on that date, and the equally long previous period ends immediately before it. Omit end_date for the original latest-finalized comparison. Dates newer than the three-day finalization buffer or periods starting before the rolling 16-month history window are rejected before spending Search Analytics quota. This changes neither the two-request budget nor the existing row-coverage limitations.
insights.content_decay includes the exact requested site_url alongside both inclusive comparison date ranges in its structured response. This identifies the Search Console property for saved decline reports without changing provider requests, OAuth permissions, quotas, or the classification heuristic.
insights.content_decay also returns observed_page_overlap counts for unique page URLs seen in the recent period, previous period, both periods, or only one period. Rows with observed clicks and impressions still count when Google omits optional average position: each unavailable previous_position or recent_position is null, and position_change is null unless both are available. A page may still qualify as likely decay when its click decline is supported by a material impression decline, but missing position never counts as ranking deterioration or improvement. A page appearing in just one returned sample is not treated as zero clicks or confirmed decay: Search Console can omit rows, and its API does not guarantee exhaustive page coverage. When comparable_count is zero, an empty decay list does not establish that the property has no declining pages. This diagnostic adds no Google requests or quota units.
To review only better-supported declines, set insights.content_decay classification_filter: "likely_decay". Other values are weak_insufficient_evidence and improving_visibility_with_click_volatility; omit it or use all for the original complete result. Filtering happens after both bounded Search Analytics responses and classification, before result pagination: result_page reflects the filtered list, while assessment_count, decay_count and observed_page_overlap continue to describe unfiltered observed evidence. It adds no Google requests, cannot recover omitted rows, and does not turn the heuristic into proof of decay.
To focus a large content-decay review on higher-impact changes, set optional min_click_loss: 20 to return only comparable pages with at least 20 fewer observed clicks in the recent period. It accepts nonnegative whole numbers, and 0 or omission preserves every returned decline; min_click_loss is echoed as null when omitted. Combine it with classification_filter: "likely_decay" to prioritize evidence-backed declines of meaningful absolute size. This filters the already returned rows before result pagination and does not alter the original assessment/decay/overlap counts, increase Google's request quota, or imply that omitted Google rows had zero clicks. The observed decline alone does not establish its cause or business impact.
observed_click_loss summarizes the number of clicks lost across returned comparable pages with declines: all_declining_pages includes every observed decline and likely_decay_pages includes only the more strongly supported classification. Both remain calculated before classification_filter, min_click_loss, or result pagination, so an analyst can see the observed magnitude without summing every result page. These are not net or property-wide traffic losses, cannot account for missing Google rows or gains on other pages, and do not establish why clicks changed. The summary uses the same two Search Analytics requests.
observed_click_gain separately reports positive click changes (all_gaining_pages) and the count of pages with increases (gaining_page_count) among URLs returned with position data in both comparison periods, before local result filtering or pagination. This provides context beside observed_click_loss without subtracting gains from declines or presenting a net/property-wide traffic change. Google may omit page rows, unmatched pages are excluded rather than assumed to have zero clicks, and this uses the same two Search Analytics requests.
For insights.cannibalization, optional country scopes searcher location (ISO 3166-1 alpha-3, such as DEU) rather than the page language. It combines with page_contains and query_contains as Google-side AND filters before pagination without additional requests. Impression shares describe only returned pages within that geography/URL scope, not property-wide query shares or proof of harmful cannibalization.
For insights.cannibalization, optional device selects desktop, mobile, or tablet for investigating overlapping URLs within the same device segment as a weekly digest or quick-wins finding. It combines with page_contains, query_contains, and country as Google-side AND filters before source pagination, without extra requests; omitting it retains all-device behavior. Observed impression shares within a device segment are not property-wide or all-device totals and do not prove harmful cannibalization.
For insights.cannibalization, use optional countries (1-10 distinct ISO alpha-3 searcher locations) and/or devices (1-3 distinct device types) to follow up multi-market quick-win and content-decay findings without narrowing their original scope. Do not supply country with countries or device with devices. Search Console applies OR within each list and AND across query, page, country and device scopes in one request before pagination. Returned impression shares are for the combined observed query/page segment, not independently measured per country/device, property-wide query shares or proof of harmful SEO cannibalization.
For insights.cannibalization, optional search_type selects web (default), image, video or news (Google Search News tab), so a cross-surface quick-wins finding can be followed by a query/page overlap investigation on the same search surface. Omission keeps the original Web request shape; explicit Image/Video/News uses Google's type before the same AND filters and source pagination, without additional API calls. Results reflect only observed rows on the selected surface, not all-search or property-wide totals. Discover and the separate Google News service are excluded because they lack query dimensions; multiple URLs alone do not prove harmful cannibalization.
For insights.cannibalization, optional data_state: "all" includes fresh, possibly preliminary query/page rows when investigating recent URL overlap. Observed impressions and impression shares may change before Google finalizes the data; they are not proof of harmful cannibalization. Omitting data_state retains Google's finalized-only request, and explicit "final" also requests only finalized rows. Results disclose data_state and preliminary_data_possible; this option keeps the same single Google request, filters, source pagination, and quota limits.
The min_page_percentage threshold is checked against each page's unrounded observed impression share; the returned impression_share is rounded to one decimal place for readability. A page just below the threshold is not treated as qualifying merely because its displayed share rounds up. These shares are based on returned query/page rows, not unique searches or an exhaustive query-level total.
Both insights.quick_wins and insights.cannibalization echo the exact requested site_url, inclusive start_date, and inclusive end_date in their structured results, so saved opportunity and overlap snapshots can be attributed to the correct Search Console property and time window. These fields are response metadata only; they do not change Google requests, quota accounting, property permissions or filters.
Search Analytics calendar dates (start_date, end_date, and comparison-period dates) use Google's Pacific Time calendar (America/Los_Angeles, UTC-8/UTC-7 depending on daylight saving time), not the caller's local timezone or UTC. This also governs the server's generated/default Search Analytics date ranges.
Platform properties. Search Console now supports platform properties for social/video accounts such as Instagram, TikTok, X, and YouTube in its UI. Google's current Search Console API documentation still defines
siteUrlusing URL-prefix andsc-domain:website-property forms and does not publish a platform-property API identifier contract.sites.listtherefore preserves every identifier Google returns and marks whether it matches the documented API grammar; the other tools deliberately reject undocumented forms instead of inventing an identifier. Use the Search Console UI/export for a platform property until Google documents API support.
Read-write mode requests the Google Search Console read-write and Indexing API scopes. Read-only mode requests only https://www.googleapis.com/auth/webmasters.readonly (plus openid and email) and does not register the six write tools or the read-only indexing.status lookup, because that lookup still requires Google's separate Indexing API scope. Read-write remains the default so existing deployments retain their current behavior; see SETUP.md to select a mode before connecting users.
Large analytics responses are bounded at the MCP boundary instead of being generated and then discarded by clients with structured-content limits. List-style tools expose start_row / next_start_row where applicable; ranked analytical tools expose limit, start_row, and result_page metadata including has_more, truncated, and byte_limit_reached. Continue paging while has_more is true rather than assuming one response is complete.
Indexing API eligibility and quotas. Google's Indexing API is not a general-purpose page submission tool — as of this writing, Google's own documentation limits it to two content types: pages with
JobPostingstructured data, and livestream pages withBroadcastEventstructured data nested insideVideoObject. Beforeindexing.request, the server fetches the target URL and checks static JSON-LD, Microdata, and RDFa markup for one of those two types; if neither is present (or the page can't be fetched), it returns an error explaining why the URL is ineligible instead of calling the Indexing API. Structured data injected only after client-side JavaScript runs cannot be confirmed by this bounded preflight and therefore fails closed. Beforeindexing.remove, the server instead confirms Google's removal precondition: the URL must already return HTTP 404/410 or expose a robotsnoindexmeta directive. Update and removal notifications share the same publish quota. Google's current documentation lists a default 200 publish requests/day/project. Its October 16, 2026 update removed an outdated quota request form, but this does not authorize exceeding published quotas or submitting unsupported content. Check your project's API access and current quota in Google Cloud Console. Google also subjects every submission to spam detection and warns that abuse or attempts to exceed quotas through multiple accounts or other means can revoke access. A successful notification is only an acknowledgment that Google received it — it does not guarantee indexing or removal completed.
Weekly digest output includes an exact-property link to the Google Search Console Performance report for quick human investigation. It preserves URL-prefix paths and sc-domain: property identifiers. The viewer must have access to that property and manually choose the same date range, search type, and filters as the digest; the link does not set those parameters, grant permissions, or make an additional Google API request.
Finalized weekly digests now report observed click-through rate (CTR) alongside clicks and impressions, with week-over-week changes expressed in percentage points, not relative percentages. Zero-impression periods do not supply a comparable CTR baseline. Preliminary snapshots display only observed current-week CTR without a week-over-week claim. These use already-requested aggregate rows and add no API calls or permission requirements.
The finalized digest links each returned top page directly to its page URL for manual review, retaining short, disambiguated display labels. Recent preliminary snapshots also link their selected page rows and show observed clicks alongside impressions for both selected pages and queries, without asserting week-over-week trends. Only ordinary HTTP(S) URLs become clickable links; malformed or unsafe URL schemes remain escaped plain text. Following a link is the reader's choice and does not make any extra Search Console API request.
Finalized digests also highlight up to three returned pages with impressions but no observed clicks, ordered by observed impressions, for follow-up query/page inspection. This uses only the existing up-to-10 current-week page rows and adds no Google API requests. It is not an exhaustive zero-click page audit: Google's top-row selection can omit pages, and absence from this section does not establish that a page had clicks, no impressions, or no opportunity.
Finalized digests separately highlight up to three returned search queries with impressions but no observed clicks, excluding diagnostic search-operator queries. Each candidate includes its observed average position when available to help distinguish ranking visibility from potential click-through issues. Average position is not a live Google ranking, and missing position is never reported as position zero. This is limited to the already-requested up-to-25 query rows (which can omit anonymized or lower-ranked queries), with no additional API requests or property-wide claims.
For explicitly recent preliminary digests, a missing aggregate totals row is not treated as zero traffic. Any separately returned page/query samples are still shown as non-exhaustive observations, without fabricated site totals or week-over-week conclusions.
For finalized digests missing either week's aggregate totals, already-returned previous-week query rows can also appear as up to three bounded, non-operator examples. They provide evidence for follow-up investigation even if current aggregate data is absent, not proof of lost traffic or zero current clicks. This uses the existing five Search Analytics requests and does not infer a week-over-week trend.
analytics.compare also returns period_comparability: inclusive calendar-day counts, equal-length status and date overlap. Raw click and impression differences are not normalized per day. A separate compact observed_common_rows_daily_average summarizes clicks and impressions across only the dimension keys returned in both periods, divided by each period's inclusive day count, with an A-minus-B daily-rate difference. These are bounded, matched-row observations, not property-wide daily totals or a daily time series; missing keys are never assumed to have zero traffic. Unequal raw window totals are not like-for-like and overlapping dates do not represent independent periods. No additional Google API requests are made.
To investigate more returned keys exclusive to one comparison period without issuing more Search Console requests, use observed_only_sample_limit: 5 (range 1-10, default 3). Each period's observed_dimension_overlap samples remain independently sorted by observed impressions and capped at the requested per-period limit, with sample_limit echoed in the result. These are not confirmed new or lost queries/pages: Google's row coverage is incomplete and an absent row is not zero traffic. The separate common-key comparison order and pagination do not change.
To prioritize comparable queries or pages from different-length windows, pass sort_by: "absolute_daily_click_change" to analytics.compare. This ranks returned common keys by the magnitude of the difference between observed clicks per inclusive calendar day, before result pagination, without adding per-row payload fields or Google requests. Omit it (or use "absolute_click_change") to preserve the original absolute raw-click-change ranking. This is a sample-scoped ranking, not proof of a property-wide trend; overlapping date ranges remain non-independent.
To surface relative click growth or loss among matched queries/pages, set sort_by: "absolute_click_percentage_change". This orders the absolute, unrounded change (period A clicks - period B clicks) / period B clicks before pagination. Only rows with positive observed baseline clicks in period B qualify: a zero-click baseline cannot be interpreted as an infinite percentage increase, and missing Google rows are never treated as zero. Small baselines can produce large but low-impact percentages, so inspect raw click counts and optionally set min_impressions_per_period or min_baseline_clicks: 20 before acting. The new baseline-click floor keeps keys with at least 20 observed clicks in period B; it also works with other sort modes, defaults to zero, and filters locally before pagination. The relative metric describes raw totals, not daily-normalized rates; unequal or overlapping periods require care. It uses the existing two Search Analytics responses without extra API calls.
To triage only material observed click movements, add min_absolute_click_change: 10 to analytics.compare. This keeps common returned queries or pages where the absolute raw A-minus-B click difference is at least ten, whether clicks rose or fell. The default of zero preserves every comparable row. This floor is independent of the selected raw, daily or percentage sort and applies before result pagination; it does not measure daily-normalized impact, infer zeros for missing keys or make additional Google requests. Combine it with click_change_direction or min_baseline_clicks for more targeted follow-up.
To find observed visibility changes even where clicks barely move, use sort_by: "absolute_impression_change" (absolute raw impression difference) or "absolute_daily_impression_change" (absolute per-day impression difference for unequal windows). These rank only keys returned in both periods, before pagination, using existing data and without extra Google requests. A large impression movement is not evidence of a change in live ranking or a property-wide trend.
For focused triage, pass click_change_direction: "loss" or "gain" to keep only returned common queries/pages whose clicks decreased or increased. The default "all" keeps every comparable key. The direction filter always refers to clicks, even when ranking by impressions: either daily sort_by option uses per-day clicks, while either raw option uses raw clicks. This distinction matters for unequal windows. Direction filtering happens before result pagination and excludes unchanged keys, while aggregate daily averages still describe all common returned keys before this local filter. It does not request additional Google data or imply that missing keys have zero traffic.
For visibility triage, impression_change_direction: "loss" or "gain" filters common returned queries/pages by observed impression movement, independent of clicks (default: "all"). Either daily sort_by option compares impressions per calendar day; either raw option compares raw totals, so unequal windows may reverse the direction. Impression and click direction filters can be combined (both must match), operate before pagination, exclude ties and leave common-row daily averages unfiltered. These are local comparisons of returned data, not evidence of changed live rankings or zero traffic for missing rows, and require no extra Google API requests.
For observed click-through movement, set sort_by: "absolute_ctr_change" to rank common returned keys by absolute CTR percentage-point change, calculated from unrounded period CTR fractions even though the displayed diff.ctr is rounded. This mode excludes rows with zero observed impressions in either period. Optionally set min_impressions_per_period: 100 to include only keys with at least 100 returned impressions in each period, before ranking and pagination; the default is zero and other sort modes remain unchanged. The filter is local and does not add Search Analytics requests. CTR movement is not evidence of changed live rankings or a statistically significant trend; these are bounded returned rows, not the full property.
To inspect CTR declines separately from improvements, add ctr_change_direction: "loss" or "gain" (default: "all"). This compares unrounded CTR fractions for keys returned in both periods and with positive impressions in each; zero-impression baselines and unchanged CTR are excluded from either directional result. It works with any sort_by, alongside existing click/impression direction filters and min_impressions_per_period, before pagination. The direction is CTR-specific even for daily click or impression ranking; no additional Google requests are made. Filtered observations are not statistically significant by themselves, and missing rows are not zero.
To inspect observed changes in average Search Console position, use sort_by: "absolute_position_change" with analytics.compare. This ranks matched returned keys by the absolute difference between unrounded period-average positions, before pagination, requiring an actual position and positive impressions in each period. It works with min_impressions_per_period and the independent click, impression and CTR direction filters; other defaults remain unchanged. Discover and Google News have no average position, so this sort is rejected for those surfaces. Lower average positions are generally better, but changes in averaged positions are not a live ranking, a unique URL rank, or proof of SEO impact. The sample is bounded to Google-returned rows and no additional Google API calls are made.
To review average-position improvements separately from declines, set position_change_direction: "improvement" or "decline" (default: "all"). Compared with period B, a lower period A average position counts as improvement, a higher one as decline. Filtering uses unrounded average positions for returned common keys with positive impressions and available positions in both periods, excludes ties, and applies before pagination with any ranking mode and impression floor. Discover and Google News reject a directional position filter before Google requests. Average-position movement is not evidence of a specific live URL ranking change, and no additional provider requests are made.
MCP clients can call read-only server.capabilities to discover the existing analytics.compare sort_by, click/impression/CTR/position direction filters, min_baseline_clicks, min_absolute_click_change, and min_impressions_per_period before selecting a reporting workflow. Its description covers returned common rows only; it does not imply complete Search Console coverage or a live ranking change.
Related MCP server: Web Validator by DigestSEO
What you can ask
For a multilingual site, call indexing.list_pages with page_contains: "/de/" to find Search-visible pages within the German URL section. The filter is applied at Google before pagination and adds no API requests. The response echoes page_contains, and its metrics describe only the matching pages returned by Search Analytics. This is not a complete index-coverage inventory: use URL Inspection to check an individual page's indexed state.
Agency reporting workflow: Read-only weekly Search Console reporting for SEO agencies walks through exact-property verification, one bounded weekly digest, matched-period comparisons, evidence checks, and a reusable human-reviewed client report. It contains no fabricated client metrics or automated outreach.
Weekly digest headings retain the URL path for a URL-prefix property (for example, example.com/de/ versus example.com/fr/) so reports for different site sections remain distinguishable. HTTP URL-prefix headings explicitly retain http:// to distinguish them from HTTPS properties; Domain property headings identify their broader property type. Common HTTPS root properties keep short host headings. This reflects Search Console's separate protocol/property scopes, not guaranteed complete traffic.
For a sc-domain: property, weekly digest top-page labels retain the complete observed URL (including host and protocol), even when only one matching path appears in the top-five sample. This avoids misattributing a page to the wrong subdomain; URL-prefix reports still use compact page paths when unambiguous. These are sampled Search Analytics rows, not a complete inventory of pages.
Finalized weekly digests now report the distinct query rows observed in each bounded week and how many appeared in both. When neither week supplies a matching returned query, stable site-level totals are not presented as evidence of stable query-level performance. These counts use the same up-to-25 query rows already fetched per period, without extra Google requests, and do not establish exhaustive query coverage.
The digest also lists up to three non-operator queries returned this week but absent from the previous week's bounded query sample, ranked by their observed impressions. These are inspection examples, not verified new searches or rankings: an unreturned query is not a measured zero, and anonymized queries may be missing. This reuses the existing five finalized Search Analytics requests without consuming more Google quota.
Finalized digests also show up to three non-operator queries observed only in the previous week's returned sample, ranked by previous impressions. These are follow-up investigation prompts, not proof of lost traffic or ranking declines: missing current rows are not measured zero. The same five bounded requests are reused.
Once connected, ask your assistant things like:
"What are my top 20 queries by clicks in the last 28 days?"
"Compare impressions for example.com this month vs last month — which pages dropped?"
"What does Google's indexed version of
https://example.com/pricingshow for index status and last crawl?""Which high-impression query/page rows have an average position between 5 and 15? Show me those optimization opportunities."
"Give me a weekly digest for
sc-domain:example.comending today.""Do any of my sitemaps have errors or warnings?"
"Using this brand regex I provide, approximate my clicks as brand vs non-brand."
"How is my site doing in Google Discover vs regular web search?"
Query regexes are a manual approximation only. Google's native brandedClassification on the Search Analytics API uses AI-assisted classification (including variants and related products). analytics.query can group by this dimension or filter with dimension: "brandedClassification", operator: "equals", expression: "BRANDED" (or "NON_BRANDED"). analytics.compare accepts the same native filter for both periods. Do not combine native branded classification with a query filter. It is available from February 21, 2026 for eligible top-level properties with sufficient traffic only; no returned classification rows does not prove zero branded or non-branded traffic.
For a guided, read-only comparison across two matched weeks, use the discoverable gsc-brand-traffic-review MCP prompt. Optionally pass string-valued countries (e.g., DEU,AUT,CHE) and devices (e.g., mobile,desktop) to focus a single regional/device segment using Google's filterLists in both periods. These prompt arguments accept comma/newline-separated text or a JSON-array string, not a raw JSON array over MCP. The results are segment-only, not site totals. It queries Google's native branded classification in the selected Search surface, reports only categories actually returned, and keeps unavailable classification distinct from measured zero traffic. Retrieving the prompt itself does not contact Google or send a report.
Search Console also has dedicated Generative AI performance reports for Search and Discover. The current documented Search Analytics API does not expose a dedicated Generative AI search type or filter selector, so this MCP does not guess one. AI Overviews and AI Mode remain included in overall web Search performance data; use the Search Console UI for the dedicated Generative AI report until Google documents API access.
Google documented the webMultimodal Search Analytics API search type on November 16, 2026. Use search_type: "webMultimodal" with analytics.query or analytics.compare to inspect Google Lens, Circle to Search, and image-upload performance on its own surface, separate from ordinary Web Search. Because these searches are image-led, the text query dimension and filters are unavailable: choose page, country, device, date, or aggregate dimensions: [] in analytics.query, and page/country/device for comparisons. search_type: "multimodal" is not a valid substitute, and a guessed searchAppearance value is not equivalent. Google may omit rows; do not infer zero traffic or sum across surfaces as if they are mutually exclusive.
To review that surface without manually assembling an analysis, use the discoverable gsc-visual-search-review MCP prompt with an exact site_url and optional end_date, page_contains, countries (ISO alpha-3) or devices. Supply optional country/device lists as comma/newline-separated strings (or JSON-array strings) as with gsc-brand-traffic-review. It guides two finalized matched-week analytics.query aggregate reads, then optionally one analytics.compare landing-page read with the same Google-side filters. The guidance does not use unsupported text-query grouping, infer zero traffic from missing rows, or present filtered samples as site totals. Getting the prompt makes no Google request; following it consumes normal read quotas and never authorizes publication or indexing changes.
Connect in your AI client
Once you've deployed the server (see SETUP.md), connect it by pasting your Worker's /mcp URL into your client:
https://<your-worker>.workers.dev/mcpClaude.ai / Claude Desktop — go to Customize → Connectors, click + → Add custom connector, enter a name and paste the
/mcpURL. Leave the optional advanced OAuth Client ID/Secret fields blank. On Team/Enterprise, an Owner or Primary Owner must first add the custom Web connector from Organization settings → Connectors; members then connect it from Customize → Connectors. On first connection, Claude opens the Google sign-in flow.Cursor — add a remote Streamable HTTP MCP server pointing at the same
/mcpURL; Cursor supports OAuth for remote HTTP MCP servers. The Add to Cursor button above targets the local npm launcher's loopback endpoint instead.ChatGPT — enable Developer mode, then create a custom MCP app from Settings → Apps → Create (admins/owners can also use Workspace settings → Apps → Create). Provide the
/mcpendpoint, select the applicable authentication option, Scan Tools, complete OAuth, then create the app. Full MCP including write/modify tools is currently available to Business and Enterprise/Edu; Pro custom MCP access is read/fetch-only, so useGSC_ACCESS_MODE=readonlyfor that path.
The /mcp endpoint is the same across clients, but each host has its own setup and permission flow.
Setup
Self-hosting means bringing your own Google OAuth credentials and Cloudflare account. The full, copy-pasteable walkthrough is in SETUP.md — including an important note about Google's OAuth verification and the 7-day refresh-token limit while your app is unverified.
Quick shape:
git clone https://github.com/AKzar1el/mcp-gsc.git
cd mcp-gsc
npm install
cp wrangler.example.jsonc wrangler.jsonc # then paste in your KV ids
# set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / TOKEN_ENCRYPTION_KEY as secrets
# choose GSC_ACCESS_MODE=readonly in wrangler.jsonc for a read-only deployment
npm run deploySee SETUP.md for every step in detail.
Development
npm install
npm test # typecheck + offline unit tests (what CI runs)
npm run dev # wrangler dev (local)
npm run test:smoke # structural smoke tests against a deploymentContributions welcome — see CONTRIBUTING.md.
Compare observed landing-page cohorts
gsc-page-cohort-review is an MCP-discoverable, read-only workflow for examining which observed top canonical page URLs changed between two adjacent finalized seven-day Search Console windows. It accepts an exact property, optional end date, Search surface (including Google Lens webMultimodal), URL-section substring, and single or multi-value country/device scopes. Country/device lists (1-10 countries, 1-3 devices) use Google-side filterLists identically in both windows. A page URL section is not a searcher locale. Compare only pages returned in both click-sorted, incomplete samples: a page absent from one week is not measured zero traffic or confirmed deindexed. Optionally inspect one page's query context when supported, preserving all filters; the multimodal surface has no query-dimension drilldown. Retrieving this prompt consumes no Google requests; following it uses ordinary read quotas. No indexing, content, publication or other writes occur, and client prompt support varies.
License
MIT © 2026 DigestSEO.
Built and maintained by Tomi Šeregi, the builder behind DigestSEO - open-source SEO tooling and search visibility software.
Available Tools
17 toolsanalytics.compareCompare Performance Between PeriodsARead-only
Compare Search Console performance metrics (clicks, impressions, CTR, average position) between two distinct date ranges (Period A vs Period B) for a selected dimension (query, page, country, device). Pagination metadata flags when either period reached the local 100,000-row safety ceiling; Search Console itself may still return only top data.
Inputs: site_url (required), end_date_a (required), end_date_b (required), start_date_a (required), +2 more. Returns: pagination, comparisons
analytics.queryQuery search analyticsARead-only
Query Google Search Console search analytics data. Returns { row_count, start_row, rows } where each row has keys (dimension values), clicks, impressions, ctr, and position. When row_count equals row_limit, the response includes next_start_row — pass it back as start_row to fetch the next page. When Google provides them, response_aggregation_type and metadata are also included; metadata may identify the first incomplete date or hour.
IMPORTANT BEHAVIORS — read before calling:
For SITE TOTALS (total impressions, total clicks, overall CTR, overall average position), call with dimensions: []. This returns a single row containing the true site-level totals. Do NOT call with dimensions: ["query"] and sum the rows — Google omits anonymized low-volume queries from per-dimension responses, so summing per-query rows will undercount.
For TOP QUERIES / PAGES / COUNTRIES / DEVICES, call with the matching dimension. Expect the returned rows to cover only a subset of total impressions; this is normal Google behavior, not a data error.
DATA FRESHNESS: Search Console data lags about 2-3 days behind real time. If the user asks about "today" or "yesterday", expect empty or partial rows for the most recent days; the latest reliably-complete date is usually 3 days ago.
AVERAGE POSITION is impression-weighted. To compute an overall position across multiple rows, use sum(position * impressions) / sum(impressions). Never plain-average the position column across rows.
CTR in the response is a 0–1 fraction. Multiply by 100 for percent.
Use search_type to query image/video/news/discover indexes separately from web.
Use dimension_filter_groups to filter by country, device, query content, page URL, or search feature. includingRegex and excludingRegex use RE2 syntax. For brand vs non-brand splits, pass a single regex filter on the 'query' dimension.
data_state defaults to 'all' which matches the GSC dashboard. Pass 'final' only when the user explicitly asks for stable, non-preliminary data.
Inputs: end_date (required), site_url (required), start_date (required), row_limit, +6 more. Returns: rows, metadata, row_count, start_row, +2 more
indexing.list_pagesList Indexed PagesARead-only
Retrieve a list of site pages that have received search impressions, serving as a proxy list of indexed pages on the site. When one date boundary is omitted, the server derives the other to target an inclusive 30-day range; generated end dates are capped at the latest complete date.
Inputs: site_url (required), end_date, row_limit, start_date. Returns: pages
indexing.requestRequest IndexingA
Requests indexing through Google's Indexing API for a URL within an owner-level Search Console property accessible to the connected Google account. Google currently restricts this API to pages containing JobPosting structured data or livestream pages containing BroadcastEvent inside VideoObject. It is not available for general webpage submission.
Inputs: url (required), site_url (required). Returns: note, result
insights.cannibalizationDetect Keyword CannibalizationARead-only
Analyze search analytics to detect instances of keyword cannibalization, where multiple pages on your site compete for the same query. Pagination metadata flags when the local 100,000-row safety ceiling stopped fetching; a false flag does not guarantee Search Console returned every underlying row.
Inputs: end_date (required), site_url (required), start_date (required), min_impressions, +1 more. Returns: candidates, pagination
insights.content_decayDetect Content DecayARead-only
Identify content decay by comparing search clicks for your site pages between two contiguous periods and finding the pages with the largest traffic drops. Pagination metadata flags when either source period reached the local 100,000-row safety ceiling; Search Console itself may still return only top data.
Inputs: site_url (required), compare_days. Returns: pagination, decay_count, decay_results, comparison_periods
insights.quick_winsIdentify SEO Quick WinsARead-only
Find search queries with at least the requested impressions that rank in a configurable striking-distance position range (8-20 by default). Returns clicks, impressions, CTR, and average position; CTR is context, not an eligibility filter. Pagination metadata flags when the local 100,000-row safety ceiling stopped fetching; a false flag does not guarantee Search Console returned every underlying row.
Inputs: end_date (required), site_url (required), start_date (required), max_position, +2 more. Returns: pagination, quick_wins
reports.weekly_digestWeekly GSC Performance DigestARead-only
Generate a plain-language weekly SEO report for one Google Search Console property. Returns a markdown digest covering the 7 days ending on end_date, with week-over-week comparison, top pages, queries gaining or losing traction, and one specific action item. Defaults end_date to today if omitted.
Inputs: site_url (required), end_date. Returns: markdown
server.capabilitiesGet server capabilities and auth statusARead-only
List every tool this server exposes, its configured access mode, and whether the user's Google Search Console connection is currently authenticated. Call this first if you're unsure what tools are available, whether the deployment is read-only, or whether the user is connected. Returns the tool catalog plus an access mode and auth status. Takes no arguments.
Inputs: no named parameters. Returns: hint, tools, server, version, +2 more
sitemaps.deleteDelete sitemapADestructiveIdempotent
Remove/delete a submitted sitemap from your Google Search Console account.
Inputs: feedpath (required), site_url (required). Returns: message
sitemaps.getGet sitemap detailsARead-only
Get status and details of a single sitemap submitted to Google Search Console.
Inputs: feedpath (required), site_url (required). Returns: sitemap
sitemaps.listList submitted sitemapsARead-only
List all sitemaps submitted for a Search Console property. Returns sitemap URLs, last submitted/downloaded dates, submitted URL counts, warning and error counts, and sitemap status. Google's deprecated sitemap indexed count is intentionally omitted. Use this when the user asks about sitemap health, submission status, or wants to audit which sitemaps are working.
Inputs: site_url (required). Returns: sitemaps
sitemaps.submitSubmit sitemapAIdempotent
Submit a new sitemap to your Google Search Console account.
Inputs: feedpath (required), site_url (required). Returns: message
sites.addAdd Search Console propertyAIdempotent
Add a new website property to your Google Search Console account. Note: Domain properties require sc-domain prefix (e.g., sc-domain:example.com), URL-prefix properties require full URL (e.g., https://example.com/).
Inputs: site_url (required). Returns: message
sites.deleteDelete Search Console propertyADestructiveIdempotent
Remove an existing website property from your Google Search Console account.
Inputs: site_url (required). Returns: message
sites.listList Search Console propertiesARead-only
List the Google Search Console properties (sites) the connected Google account has access to. Returns an array of { siteUrl, permissionLevel }. Call this when the user asks 'what sites do I have?' or 'what properties are connected?', or when the user asks about SEO for a site and hasn't specified which property. Also useful as a discovery step before calling other tools that require a site_url argument.
Inputs: no named parameters. Returns: sites
urls.inspectInspect URL index statusARead-only
Inspect a single URL's index status in Google. Returns: whether the URL is indexed, last crawl date, indexing state, mobile usability, rich-results eligibility, and any AMP results. Use this when the user asks 'is X indexed?', 'why isn't X showing in Google?', or wants a deep look at one specific page. For bulk checks across many URLs, call this tool repeatedly — there is no batch endpoint — but note Google caps URL inspection at roughly 2,000 calls per property per day.
Inputs: site_url (required), inspection_url (required), language_code. Returns: inspection_result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools are scoped to a distinct resource or analysis, and the descriptions clearly separate analytics.query from analytics.compare and the insights.* helpers. Minor overlap remains between indexing.list_pages and analytics.query with page dimensions, and the three insights tools may look interchangeable until read closely, but an agent can generally select correctly.
Tool names follow a consistent dot-namespaced pattern (sites.list, sitemaps.submit, analytics.compare) with snake_case for multi-word operations. The set is readable and predictable, though insights.cannibalization and reports.weekly_digest use noun-phrase operations rather than the verb-first style used by most names.
Seventeen tools is slightly above the ideal 3-15 range, but the count reflects the server's broad scope: property management, sitemaps, URL inspection, analytics, insights, indexing, and reporting. Each tool covers a distinct GSC workflow, so the size feels justified rather than bloated.
The server covers the core Google Search Console lifecycle comprehensively: site add/list/delete, sitemap submit/get/list/delete, URL inspection, analytics querying, comparison, insights, indexing, and reporting. There are no critical dead ends, and the few absences such as batch URL inspection are limitations of the underlying API rather than gaps in the tool surface.
Maintenance
Related MCP Connectors
SEO MCP server: Search Console, GA4, Crawler and AI visibility across 6 AI engines
Google Search Console, GA4 and PageSpeed MCP server for Claude, ChatGPT and Cursor. Free, hosted.
Hosted, read-only Google Search Console MCP: performance, comparisons, URL inspection, sitemaps.
SEO MCP: Search Console, GA4, SERP and domain data, rank tracking, AI citations and site fixes.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for Google Search Console, URL Inspection & Indexing API — search analytics, sitemap management, and batch indexing13154 npm8MIT
- AlicenseAqualityBmaintenanceEnables AI coding assistants to validate HTML/CSS markup using W3C APIs, perform technical SEO audits, check broken links, and validate JSON-LD schemas directly in local workspaces.8413 npm9MIT
- AlicenseAqualityBmaintenanceAI visibility tracker MCP server. Track brand citations across ChatGPT, Claude, Perplexity, Gemini & Google AI Overviews. Self-host on Cloudflare Workers. GEO/AEO.12238 npm40MIT
- AlicenseNot gradedqualityNot gradedmaintenanceSelf-hosted Google Search Console MCP server deployable to Cloudflare Workers in 15 minutes. Enables querying GSC data (sites, search analytics, URL inspection, sitemaps) via natural language through MCP-capable clients like ChatGPT or Claude.MIT