mcp-gsc

Part of the DigestSEO suite of open-source SEO tools.
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-gsc
On 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/mcp
Self-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/mcp
OpenAI Codex CLI / IDE
codex mcp add gsc --url http://127.0.0.1:8080/mcp
Codex 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@digestseo
The 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-gsc
The 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.
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 |
|---|
server.capabilities | Read | List every tool this server exposes and report local Google credential state. connected means a stored refresh credential is present; the response also exposes auth_status_basis and provider_auth_live_verified: false because this discovery call does not probe Google. A later Google tool call can still require reconnection if the credential expired or was revoked. Takes no arguments. |
sites.list | Read | List the Search Console properties the connected Google account can access (siteUrl, permissionLevel). |
sites.get | Read | Retrieve one exact Search Console property and the connected account's permission level for it. |
analytics.query | Read | Impressions, clicks, CTR, and average position over a date range, with dimensions, filters, safe pagination, and selectable search type. Pass dimensions: [] for true site totals; Google's aggregate row may omit keys. Search Analytics does not guarantee every data row and can return only top rows, so exhausting local pagination is not proof that the provider dataset is exhaustive. data_state: "all" can include fresh preliminary data, while final returns only finalized data; responses echo data_state plus preliminary_data_possible, and date/hour groupings preserve Google's incomplete-data boundary metadata when returned. Search appearance discovery is a two-step workflow: group by searchAppearance alone to discover the exact values Google returns for the property, then filter to one returned value in a separate query when grouping by page/query/country/device/date/hour. For search_type: "discover" or "googleNews", position_supported is false; those reports expose clicks, impressions, and CTR but not average position, so returned rows can omit position, and query grouping/filtering is unavailable. Search Console's dedicated Generative AI performance reports are not exposed by the current documented Search Analytics API as a dedicated search type or filter selector; generative_ai_report_isolatable is therefore false. Search Console's new web multimodal UI filter is likewise not exposed as a documented Search Analytics API selector; multimodal_report_isolatable is therefore false. |
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 optional query_contains (e.g. seo) to narrow query topics at Google before pagination; scoped rows are not all queries for that page. insights.query_pages accepts optional page_contains (e.g. /de/) to filter page URLs at Google before pagination; those rows are not property-wide. Both accept optional country (ISO alpha-3, e.g. DEU) for searcher geography (not page language) and device (desktop, mobile, or tablet) to preserve the reporting device scope. Filters are ANDed with the exact query/page and optional substring at Google before pagination; default omitted device includes all devices. Results reflect only the selected scopes and available Search Analytics rows, not a property-wide or exhaustive dataset. These query-centric helpers support web, image, video, and the Search results News tab; Discover and the Google News report are excluded because they do not expose 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. |
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 robots noindex meta directive. Google's receipt does not prove removal completed; use URL Inspection for indexed-state evidence. |
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 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 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, 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 siteUrl using URL-prefix and sc-domain: website-property forms and does not publish a platform-property API identifier contract. sites.list therefore 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 JobPosting structured data, and livestream pages with BroadcastEvent structured data nested inside VideoObject. Before indexing.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. Before indexing.remove, the server instead confirms Google's removal precondition: the URL must already return HTTP 404/410 or expose a robots noindex meta 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.
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 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 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, 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.
What you can ask
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.
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/pricing show 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.com ending 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. Search Console's native Branded/Non-branded filter uses Google's own AI-assisted classification (including language variants, typos, and associated products/services), and that native classifier is not exposed as a Search Analytics API filter.
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.
As of September 24, 2026, Search Console also has a web multimodal performance filter in the UI for searches such as Lens, Circle to Search, image uploads, and Chrome image search. The current Search Analytics API and Discovery document still expose only web, image, video, news, discover, and googleNews search types, so this MCP does not invent search_type: "multimodal" or guess a searchAppearance value. Use the Search Console UI for isolated multimodal reporting until Google documents API access.
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/mcp
- Claude.ai / Claude Desktop — go to Customize → Connectors, click + → Add custom connector, enter a name and paste the
/mcp URL. 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
/mcp URL; 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
/mcp endpoint, 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 use GSC_ACCESS_MODE=readonly for 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
npm run deploy
See SETUP.md for every step in detail.
Development
npm install
npm test
npm run dev
npm run test:smoke
Contributions welcome — see CONTRIBUTING.md.
License
MIT © 2026 DigestSEO.
Built and maintained by Tomi Šeregi, the builder behind DigestSEO - open-source SEO tooling and search visibility software.