Google Search Console MCP
This MCP server lets an AI client read and, in read-write mode, manage Google Search Console data for connected properties.
Check server capabilities, access mode, and Google authentication status.
List Search Console properties and permission levels.
Query search analytics by date, dimensions, filters, search type, and pagination; compare periods and list pages receiving impressions.
Inspect a URL's index status and list or retrieve sitemap details.
Run SEO analyses for quick wins, keyword cannibalization, and content decay.
Generate weekly performance digests.
In read-write mode, add/delete properties, submit/delete sitemaps, and request Indexing API notifications for eligible JobPosting or livestream pages.
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 |
| Read | Drill from one exact page to its Search Console queries, or from one exact query to the pages Google surfaced for it, with |
| 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. |
| Read | Inspect Google's indexed versions of up to 10 URLs sequentially in one call while preserving input-order results. |
| Read | List submitted sitemaps or retrieve one sitemap's details. |
| Read | Surface average-position opportunity rows, query/page overlap, and evidence-ranked click declines. Quick wins accepts optional |
| 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. |
| Read | Generate a plain-language seven-day performance report with movers, top pages, and evidence-based next steps. Optional |
| Write | Add or remove a property from the connected account's Search Console site set. |
| Write | Submit or remove a sitemap. |
| Read | Read Google's latest successful Indexing API |
| Write | Requests indexing through Google's Indexing API. Google currently restricts this API to pages containing |
| Write | Request a |
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. 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.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. Only rows with position data count as comparable. 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
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.
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.
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.
Related MCP server: Web Validator by DigestSEO
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.
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. 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/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.
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
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.
Read-only Google Search Console MCP server for AI assistants.
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.8383 npm9MIT
- AlicenseAqualityBmaintenanceAI visibility tracker MCP server. Track brand citations across ChatGPT, Claude, Perplexity, Gemini & Google AI Overviews. Self-host on Cloudflare Workers. GEO/AEO.12437 npm39MIT
- 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