Skip to main content
Glama
Google Search Console MCP

Google Search Console MCP

README.md
# mcp-gsc

<!-- Logo asset for marketplace submissions: assets/logo-400.png (400x400). -->

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-remote%20server-8A2BE2)](https://modelcontextprotocol.io)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.AKzar1el%2Fmcp--gsc-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.AKzar1el/mcp-gsc)
[![CI](https://github.com/AKzar1el/mcp-gsc/actions/workflows/ci.yml/badge.svg)](https://github.com/AKzar1el/mcp-gsc/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/%40digestseo%2Fmcp-gsc.svg)](https://www.npmjs.com/package/@digestseo/mcp-gsc)
[![mcp-gsc MCP server](https://glama.ai/mcp/servers/AKzar1el/mcp-gsc/badges/score.svg)](https://glama.ai/mcp/servers/AKzar1el/mcp-gsc)

Part of the **[DigestSEO](https://digestseo.com/)** suite of open-source SEO tools.

- Product: [digestseo.com/gsc-mcp](https://digestseo.com/gsc-mcp/)
- Engineering case study: [DigestSEO MCP Suite — AI visibility, Search Console, web validation, and trend intelligence](https://tomiseregi.si/projects/digestseo-mcp-suite)
- Support: [digestseo.com/support](https://digestseo.com/support/)
- Privacy: [digestseo.com/privacy](https://digestseo.com/privacy/)

The self-hosting launcher is available as [`@digestseo/mcp-gsc`](https://www.npmjs.com/package/@digestseo/mcp-gsc). For new analytics/reporting-only connections, explicitly start in read-only mode:

```bash
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](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](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](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](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**

```bash
claude mcp add --transport http gsc http://127.0.0.1:8080/mcp
```

**OpenAI Codex CLI / IDE**

```bash
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)**

[![Add GSC MCP to VS Code](https://img.shields.io/badge/VS_Code-Add_GSC_MCP-007ACC?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=gsc&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22http%3A%2F%2F127.0.0.1%3A8080%2Fmcp%22%7D)

The button adds only the local Streamable HTTP connection; it does **not** start the npm launcher or configure Google OAuth. Follow [SETUP.md](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**

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=gsc&config=eyJ1cmwiOiJodHRwOi8vMTI3LjAuMC4xOjgwODAvbWNwIn0%3D)

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](https://cursor.com/agents); Cursor supports HTTP MCP servers and OAuth there. Do not reuse the loopback URL for a Cloud Agent.

**GitHub Copilot CLI**

```bash
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**

```bash
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**

[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=mcp-gsc&config=%7B%22url%22%3A%22http%3A%2F%2F127.0.0.1%3A8080%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)

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](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels). 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](#connect-in-your-ai-client) below.

A self-hostable [Model Context Protocol](https://modelcontextprotocol.io) (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](https://workers.cloudflare.com/) 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 |
|---|---|---|
| **`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 CTR is context rather than an eligibility filter. 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) so an empty comparison is distinguishable from a lack of common returned keys. A key absent from one non-exhaustive Search Analytics response is not assumed to have zero metrics. 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. Because its comparison contract includes average position, it excludes Discover and Google News. `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. 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. 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 `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](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.

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.

## What you can ask

**Agency reporting workflow:** [Read-only weekly Search Console reporting for SEO agencies](docs/agency-weekly-reporting.md) 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/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](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](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:

```bash
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 deploy
```

See **[SETUP.md](SETUP.md)** for every step in detail.

## Development

```bash
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 deployment
```

Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE) © 2026 DigestSEO.

---

*Built and maintained by [Tomi Šeregi](https://tomiseregi.si), the builder behind [DigestSEO](https://digestseo.com) - open-source SEO tooling and search visibility software.*

TDQS

A4.1/5.0

Scored across 17 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness5/5

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

ActivityActive
ResponsivenessOutdated data