Skip to main content
mcp-gsc product mark
Open source · MIT licensed

GSC MCP server for Google Search Console.

mcp-gsc connects Claude, ChatGPT, Cursor, or another MCP client to Google Search Console. Query search analytics, inspect URLs, manage sitemaps, and run focused SEO diagnostics with Google OAuth.

Recommended mode
Read-only
Auth method
Google OAuth
Run options
npm / Worker
License
MIT
mcp-gsc Google Search Console data overview with search performance, indexing, and sitemap signals
mcp-gsc brings Search Console performance, indexing, and sitemap data into your MCP client.

npm · Google Search Console MCP

Install the GSC MCP server locally

Use npm for a private, same-machine Streamable HTTP server. Google OAuth and credentials must be configured before this command will run; this is not a one-click connection.

1. Prepare Google access

  1. Node.js ^22.18.0 / >=24.11.0 + npm
  2. Use a Google account with access to the Search Console property you want to analyze.
  3. Create a Google Cloud OAuth client, enable the required APIs, and authorize the exact local redirect URI.
  4. Set these three environment variables using the version-matched setup guide. TOKEN_ENCRYPTION_KEY must be valid base64 for exactly 32 random bytes.
    GOOGLE_CLIENT_IDGOOGLE_CLIENT_SECRETTOKEN_ENCRYPTION_KEY

Register this exact redirect URI in Google Cloud. The host, port and path must match; localhost and 127.0.0.1 are not interchangeable.

http://127.0.0.1:8080/google/callback

localhost ≠ 127.0.0.1

Full setup guide (SETUP.md)

2. Start the local server

After configuring your credentials in your shell, run the npm launcher. Use the appropriate read-only shell setting below for analytics-only work.

The launcher defaults to readwrite. For analytics-only use, choose readonly before authorizing Google; write tools are then not registered.

Bash / zsh

export GSC_ACCESS_MODE=readonly
npx -y @digestseo/mcp-gsc

PowerShell

$env:GSC_ACCESS_MODE = 'readonly'
npx -y @digestseo/mcp-gsc

Local endpoint · Streamable HTTP

http://127.0.0.1:8080/mcp

3. Connect your MCP client

Keep the launcher running and register its local Streamable HTTP endpoint from a client on the same computer. This is HTTP, not stdio.

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

Cursor

In Cursor, add a Streamable HTTP MCP server named gsc with this URL (local Cursor only).

http://127.0.0.1:8080/mcp

ChatGPT / Claude.ai

ChatGPT and cloud-hosted Claude cannot reach your computer's 127.0.0.1. Use your own HTTPS Worker or an available secure MCP tunnel, subject to account and workspace permissions.

Prefer remote access?

Prefer remote access?

The existing Cloudflare Workers deployment is still supported. It requires your own Cloudflare configuration and Google OAuth setup, and offers an HTTPS endpoint for eligible remote clients. The deploy example below uses Bash; follow SETUP.md for the full procedure.

A reproducible read-only workflow

From an authorized property to defensible search evidence

A useful GSC MCP connection should answer a concrete question without guessing about your rankings. This example uses the actual query_search_analytics tool argument contract; the site address is a placeholder, not a live data response.

MCP tool arguments — property-wide Web totals

Use a site identifier returned by list_sites and choose a finalized date range. These are MCP arguments, not a terminal command.

{
  "site_url": "https://your-verified-site.example/",
  "start_date": "2026-11-01",
  "end_date": "2026-11-07",
  "search_type": "web",
  "data_state": "final",
  "dimensions": []
}

01. Confirm access

Run get_capabilities, then list_sites. A domain property uses sc-domain:example.com; a URL-prefix property uses its full HTTPS URL including the trailing slash. They are not interchangeable.

02. Read the response, not a fabricated screenshot

The tool returns row_count, start_row and rows with clicks, impressions, CTR and average position. In this example dimensions: [] requests one property-level total row, not an incomplete sum of search queries.

03. Find what changed

Repeat on equivalent periods, then use dimensions: ["query"] or ["page"] to investigate the visible subset. Google omits anonymized queries; a missing row is not proof of zero traffic. Average position must be impression-weighted when combining rows.

Access boundary: set GSC_ACCESS_MODE=readonly before authorizing Google to keep mutation tools unregistered. Search Console reports can lag by several days; data_state: "final" excludes preliminary rows. This walkthrough deliberately publishes no private Search Console results, account identifiers or example visit estimates.

About

What is mcp-gsc?

mcp-gsc is a self-hostable Model Context Protocol server that bridges your AI client directly with the official Google Search Console API.

Normally, querying sitemap health or downloading keyword performance logs requires downloading CSVs or building custom scripts. Run the published npm package on your own machine or deploy a Cloudflare Worker for remote HTTPS access, then connect through Google OAuth.

Use the free keyword research tool when you are still choosing an intent or topic; use Search Console after publishing to validate the queries, impressions, clicks, CTR, and positions Google actually reports.

For Google's separately exported Web: multimodal performance report, including Google Lens, use the browser-local multimodal analyzer. This manual CSV workflow is separate from mcp-gsc's documented API capabilities.

To compare Google Search discovery of your authorized Instagram, TikTok, X, or YouTube accounts, use the free browser-local Social Search Performance Comparator with separate Search Console exports. This does not imply platform-property support in mcp-gsc's API.

For analytics-only use, configure GSC_ACCESS_MODE=readonly before signing in. The local launcher stores encrypted session state in ~/.mcp-gsc/state by default; a self-hosted Worker uses storage in your Cloudflare account.

Tools

Exposed Server Capabilities

Tools cover analytics, URL inspection, sitemaps, indexing, SEO diagnostics, and a weekly performance digest. The list includes optional write tools; GSC_ACCESS_MODE=readonly registers only nonmutating capabilities.

01 get_capabilities

Lists available capabilities and reports whether your Google Search Console connection is currently authenticated.

02 list_sites

Retrieves a list of all Search Console properties the connected Google account has permissions to access.

03 query_search_analytics

Queries search metrics (clicks, impressions, CTR, position) over custom ranges filtered by query, page, device, or country.

04 inspect_url

Fetches Google's URL Inspection API report for the indexed version, including indexing status and crawl details (not a live URL test).

05 list_sitemaps

Lists all sitemaps submitted for the property along with submission, crawl status, and detected warning/error counts.

06 add_site

Adds a Search Console property to the connected Google account.

07 delete_site

Removes a Search Console property from the connected Google account.

08 submit_sitemap

Submits a sitemap for a Search Console property.

09 delete_sitemap

Removes a submitted sitemap from a Search Console property.

10 get_sitemap

Retrieves detailed status for one submitted sitemap.

11 identify_quick_wins

Finds high-impression queries ranking in positions 8–20 with low click-through rate.

12 detect_cannibalization

Finds queries where multiple pages compete for search visibility.

13 detect_content_decay

Identifies pages with the largest search-click declines between two periods.

14 request_indexing

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.

15 list_indexed_pages

Lists pages that have received Search Console impressions as a practical indexing proxy.

16 compare_performance

Compares clicks, impressions, CTR, and position across two date ranges.

17 weekly_digest

Generates a plain-language weekly SEO report with movers and one recommended action.

Setup

Connect your self-hosted Worker

Claude Code

After completing Cloudflare and Google OAuth setup, register your HTTPS Worker:

claude mcp add --transport http gsc \
  https://YOUR-WORKER.workers.dev/mcp

Cursor

Add a new HTTP server in your Cursor settings:

  • Name: gsc
  • URL: https://YOUR-WORKER.workers.dev/mcp

Deploy

Self-host on Cloudflare Workers

For remote clients, configure your own HTTPS Worker, Google OAuth and Cloudflare storage. This Bash-oriented outline is not a complete setup guide.

~/mcp-gsc · deploy
git clone https://github.com/AKzar1el/mcp-gsc.git
cd mcp-gsc && npm install
npx wrangler login
cp wrangler.example.jsonc wrangler.jsonc
# ... configure KV namespaces and the Durable Object per SETUP.md
npx wrangler deploy
Cloudflare and OAuth setup guide →

Explore the open-source GSC MCP server.

Configure Google OAuth for local npm or deploy your own Cloudflare Worker.