Google Search Console

mcp-gsc

[License: MIT] [MCP] [MCP Registry] [CI] [npm version] [mcp-gsc MCP server]

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-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)

[Add GSC MCP to VS Code]

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

[Add to 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-gsccopilot 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

[Add to 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.

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.

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.

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.gitcd mcp-gscnpm installcp 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 deploymentnpm run deploy

See SETUP.md for every step in detail.

Development

npm installnpm 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.

License

MIT © 2026 DigestSEO.

Built and maintained by Tomi Šeregi, the builder behind DigestSEO - open-source SEO tooling and search visibility software.