Skip to main content
Glama
google-search-console-mcp-server

google-search-console-mcp-server

Google Search Console MCP server

Bring your search performance into the conversation.

Investigate queries, pages, indexing and sitemaps through a read-only MCP server.

Release CI License: Apache 2.0 Node

Watch the demo · What's new · Install · Tool reference · Try hosted getmcpads

Watch the getmcpads product demo: campaign review in Claude

Play the 27-second product film

The film demonstrates hosted getmcpads with staged data. Its creative galleries and MCP Apps interface belong to the hosted product. This repository provides the standalone native API tools.

20 read tools · Read-only by design.

Run locally with your own platform credentials and a client that supports stdio MCP, such as Claude Desktop, Claude Code or Cursor. Your requests go directly to the platform. For managed connections, including supported ChatGPT setups, use the hosted option.

What's new

v2.0.0: Native tools and security update · September 20, 2026

  • Bound automatic pagination to four pages, 100,000 rows and a 30-second total deadline.

  • Expose pagination and truncation diagnostics while preserving hourly data and native metadata.

  • Remove provider error bodies from logs and errors; bound search-type comparison fan-out.

  • Require Node.js 22.12 or newer and check Node 22/24 in CI.

  • Update vulnerable dependencies and regenerate the MCP catalog.

Full changelog · Source synchronization details · All releases

Upgrade notes

Requires Node.js 22.12 or newer. CI covers Node 22 and 24. Version 2.0.0 drops Node 18 and 20 support. Hosted creative integrations and MCP Apps UI are outside this release.

Related MCP server: gsc-mcp

Install this release

This is a GitHub source release. npm and MCP Registry versions are published separately. The commands below select this exact version; unpinned npx examples later in this document select the version currently available on npm.

git clone --branch v2.0.0 --depth 1 https://github.com/getmcpads-com/google-search-console-mcp-server.git
cd google-search-console-mcp-server
npm ci
npm run build

Configure your MCP client to run node with the absolute path to dist/cli.js and the platform credentials documented below.

Prefer a managed connection? Use Google Search Console with hosted getmcpads. Connect your account, select the data your assistant may access and use the hosted MCP connection. See the site for current features and plans.

What you get

20 read tools

Search Analytics, sites, sitemaps, URL Inspection, and analyses built on top of them

SEO analyses, not just an API wrapper

Cannibalisation detection, query clustering, wins and losses between periods, indexation watchlists, large-site sampling plans

7 resources

Live catalogues the model can read: metrics, dimensions, filters, compatibility rules, 8 workflow recipes, read-only playbooks

Quota guardrails

Every URL Inspection call is capped at 10 URLs, so one exploratory question cannot burn a day of quota

No writes at all

Not a flag, a property of the code. See below

What it does beyond fetching rows

Search Console answers questions about rows. Most real questions are about change: which queries did we lose, which pages compete for the same term, is indexing drifting.

These tools do that work rather than leaving it to the model:

Tool

Question it answers

gsc_detect_cannibalization

Which pages compete for the same query

gsc_find_losses_gains

What we won and lost between two periods

gsc_cluster_queries

Which queries belong to the same intent

gsc_compare_search_types

How web, image, video and news differ

gsc_analyze_search_appearance_trends

How rich results evolve

gsc_indexation_watchlist

Which URLs changed indexing verdict

gsc_plan_large_site_sampling

Which URLs to inspect, when you cannot inspect them all


One thing to know before you trust a number

Search Console returns a top N, not a site total.

When you query with a dimension such as query or page, the API returns the highest ranked rows up to your row limit, ordered by clicks. Summing the clicks of those rows does not give you the site total: the long tail is missing, and on a large site it can be most of the traffic.

To get a real total, query without dimensions. To compare periods, compare like with like: same dimensions, same row limit, same search type.

gsc_query_search_analytics reports what it actually returned, and gsc_validate_query checks a combination before it runs. But the arithmetic mistake is yours to avoid, and it is the most common one in Search Console analysis.

Two other limits worth carrying in your head:

  • Roughly 16 months of history. Anything older is gone, not slow.

  • Data settles over about three days. gsc_get_data_freshness tells you what is final.


Read-only, and why it stays that way

There are no write tools, and no environment variable that adds any. The Search Console API can submit and delete sitemaps, add and remove properties, and request indexing. This server exposes none of that.

The scope it asks for reflects that: webmasters.readonly, not webmasters. Even if the model tried, the token cannot write.

Our ad platform servers, where writes make sense, do have them, guarded by a mandatory preview: Meta Ads · Google Ads · TikTok Ads

The hosted version at getmcpads.com keeps the same rule: Search Console stays read-only there too.


Getting credentials

Three values, obtained once.

1. OAuth client

In a Google Cloud project, enable the Google Search Console API, then create an OAuth client under APIs & Services → Credentials. Choose Desktop app for local use. Note the client ID and client secret.

2. Refresh token

Run the OAuth consent flow once, signed in as a Google account that owns or can read your properties, and keep the refresh token. Request webmasters.readonly and nothing more.

📖 Google OAuth for installed apps

The refresh token does not expire. Use an OAuth client dedicated to this server so you can revoke it on its own.

For a quick trial you can set GSC_ACCESS_TOKEN to a short-lived token instead, but it expires within the hour and is useless for daily work.

If setting up an OAuth client is more than you want to do for one property, getmcpads.com handles the consent flow for you and gives you the same tools behind a hosted endpoint.

3. Site URL, optional

Set GSC_SITE_URL to avoid passing it on every call. Both property forms work:

Property type

Value

URL-prefix

https://example.com/ (the trailing slash matters)

Domain

sc-domain:example.com

List what you can reach with gsc_list_sites, and run gsc_health_check as your first call. It verifies the credentials without printing any secret.


Setup

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@getmcpads/google-search-console-mcp-server"],
      "env": {
        "GSC_CLIENT_ID": "your-client-id",
        "GSC_CLIENT_SECRET": "your-client-secret",
        "GSC_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Restart Claude Desktop. Ask it: "which queries did we lose last month?".

Claude Code

claude mcp add search-console --env GSC_CLIENT_ID=... --env GSC_CLIENT_SECRET=... --env GSC_REFRESH_TOKEN=... -- npx -y @getmcpads/google-search-console-mcp-server

Cursor

.cursor/mcp.json in your project, same shape as the Claude Desktop config above.

From source

git clone https://github.com/getmcpads-com/google-search-console-mcp-server.git
cd google-search-console-mcp-server
npm install && npm run build
cp .env.example .env   # then fill in your credentials
npm start

Configuration

Variable

Default

Meaning

GSC_CLIENT_ID

none

OAuth client ID

GSC_CLIENT_SECRET

none

OAuth client secret

GSC_REFRESH_TOKEN

none

From the consent flow

GSC_ACCESS_TOKEN

none

Alternative to the three above, expires within the hour

GSC_SITE_URL

none

Optional default property

LOG_LEVEL

info

debug, info, warn, error

Either the three OAuth values, or GSC_ACCESS_TOKEN. The server refuses to start with neither.

npm run doctor

Tools

Every tool is listed below. See server-card.json for complete parameter and output schemas.

Tool

Purpose

gsc_list_sites

List all Google Search Console properties accessible with the current credentials.

gsc_get_site

Get one Search Console property and its exact permission level (read-only sites.get).

gsc_health_check

Verify Google Search Console read-only authentication, visible properties, configured default site, and permission levels without exposing tokens.

gsc_query_search_analytics

Query Google Search Console Search Analytics.

gsc_inspect_url

Inspect a URL for Google indexing status, crawl info, mobile usability, AMP, and rich results.

gsc_bulk_inspect_urls

Inspect multiple URLs with a conservative sequential limit and normalized URL Inspection results.

gsc_list_sitemaps

List sitemaps submitted for a Search Console property, including processing status and submitted/indexed counts.

gsc_get_sitemap

Get one submitted sitemap by full feed path, including type, fetch state, warnings/errors, and submitted/indexed content totals.

gsc_get_sitemap_health

Return an enriched read-only sitemap health summary with status totals, submitted/indexed content counts, warnings, and errors.

gsc_compare_search_types

Compare performance across Search Console search types: web, image, video, news, discover, and Google News.

gsc_get_data_freshness

Detect the most recent date with Search Analytics data by querying recent daily rows.

gsc_monitor_indexation_freshness

Read-only monitoring snapshot for Search Analytics freshness, sitemap indexation totals, and an optional small URL Inspection sample.

gsc_track_sitemap_deltas

Read-only sitemap delta tracker.

gsc_analyze_search_appearance_trends

Analyze structured data and rich-result trend signals via the Search Analytics searchAppearance dimension when GSC exposes it.

gsc_plan_large_site_sampling

Build a read-only URL Inspection sampling plan for large sites from sitemap risk signals and Search Analytics page performance.

gsc_indexation_watchlist

Read-only URL Inspection watchlist for critical URLs.

gsc_find_losses_gains

Compare two periods for query or page performance and return click/impression/CTR/position deltas.

gsc_cluster_queries

Cluster Search Console queries by simple tokens and intent signals: brand/non-brand, question, category, and topic tokens.

gsc_detect_cannibalization

Detect queries where multiple pages compete for clicks/impressions in Search Analytics query-page rows.

gsc_validate_query

Validate a Search Console metric/dimension/search type combination before executing it.

URI

Contents

gsc://manifest

What this server exposes, and which tool to run first

gsc://metrics

The 8 Search Analytics metrics, raw and derived

gsc://dimensions

The 7 dimensions and where they are valid

gsc://filters

The 5 filter operators and their accepted values

gsc://compatibility

Which dimensions work with which search types and data states

gsc://recipes

8 step-by-step workflows

gsc://p2-readonly-playbooks

Monitoring playbooks and their invariants


Security

  • The client secret and refresh token are never logged, at any log level, or written to disk.

  • Four hosts are contacted, and only four: searchconsole.googleapis.com and www.googleapis.com for the API, oauth2.googleapis.com and accounts.google.com for OAuth. A test fails the build if a fifth host appears in the source.

  • No fetch follows a redirect. Every outbound call sets redirect: "error", so a redirect cannot forward a bearer token or client secret to another host. A test fails the build if any fetch omits this.

  • The scope is webmasters.readonly. The token itself cannot write.

  • No telemetry. The server makes no network call other than to Google.

Full policy: SECURITY.md.


Looking for a managed, multi-platform version?

Try hosted Search Console if you want to use this source without operating a local server. getmcpads also connects advertising, Search Console and GA4 through one MCP URL. Source availability and plan limits are listed on the site; connecting an account is still required.

  1. Follow the Search Console connection guide.

  2. Select the account or property your assistant may read.

  3. Connect Claude, ChatGPT or Codex.

  4. Try a read-only review: “Find which pages and queries account for a change in organic clicks. State missing data and do not change anything.”

See the current hosted tool catalogue and pricing before choosing a paid plan. This Apache 2.0 adapter remains independently useful with your own credentials.


Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md. Please read SECURITY.md before reporting anything security-related.

Licence

Apache License 2.0. See also NOTICE.

Google and Google Search Console are trademarks of Google LLC. This project is not affiliated with, endorsed by, or sponsored by Google LLC. It is an independent client of a public API.

MCP contracts and desktop bundle

Every tool declares read/write annotations, parameter descriptions and a structured output schema. Successful calls expose the payload as structuredContent.result; errors retain isError: true. The generated server card contains definitions only.

Run npm run bundle -- /path/to/output to build a .mcpb desktop bundle from the current catalog. Credentials are entered locally during installation. This server remains read-only.

More from getmcpads

Meta Ads · Google Ads · Google Analytics 4 · TikTok Ads · Pinterest Ads · X Ads

Maintained by Emmanuel at getmcpads. Questions: hello@getmcpads.com.

Available Tools

20 tools
gsc_bulk_inspect_urlsgsc bulk inspect urlsA
Read-onlyIdempotent

Inspect multiple URLs with a conservative sequential limit and normalized URL Inspection results. Quota: 2000 requests/day/property.

Inputs: urls (required), siteUrl, languageCode, continueOnError. Returns: result

gsc_cluster_queriesgsc cluster queriesA
Read-onlyIdempotent

Cluster Search Console queries by simple tokens and intent signals: brand/non-brand, question, category, and topic tokens.

Inputs: limit, siteUrl, dateRange, brandTerms, +5 more. Returns: result

gsc_compare_search_typesgsc compare search typesB
Read-onlyIdempotent

Compare performance across Search Console search types: web, image, video, news, discover, and Google News.

Inputs: siteUrl, dateRange, datePreset, searchTypes. Returns: result

gsc_detect_cannibalizationgsc detect cannibalizationA
Read-onlyIdempotent

Detect queries where multiple pages compete for clicks/impressions in Search Analytics query-page rows.

Inputs: topN, limit, siteUrl, minPages, +5 more. Returns: result

gsc_find_losses_gainsgsc find losses gainsA
Read-onlyIdempotent

Compare two periods for query or page performance and return click/impression/CTR/position deltas.

Inputs: topN, limit, sortBy, siteUrl, +6 more. Returns: result

gsc_get_data_freshnessgsc get data freshnessA
Read-onlyIdempotent

Detect the most recent date with Search Analytics data by querying recent daily rows.

Inputs: siteUrl, searchType, lookbackDays. Returns: result

gsc_get_sitegsc get siteA
Read-onlyIdempotent

Get one Search Console property and its exact permission level (read-only sites.get).

Inputs: siteUrl. Returns: result

gsc_get_sitemapgsc get sitemapA
Read-onlyIdempotent

Get one submitted sitemap by full feed path, including type, fetch state, warnings/errors, and submitted/indexed content totals.

Inputs: feedpath (required), siteUrl. Returns: result

gsc_get_sitemap_healthgsc get sitemap healthA
Read-onlyIdempotent

Return an enriched read-only sitemap health summary with status totals, submitted/indexed content counts, warnings, and errors.

Inputs: siteUrl. Returns: result

gsc_health_checkgsc health checkA
Read-onlyIdempotent

Verify Google Search Console read-only authentication, visible properties, configured default site, and permission levels without exposing tokens.

Inputs: siteUrl. Returns: result

gsc_indexation_watchlistgsc indexation watchlistA
Read-onlyIdempotent

Read-only URL Inspection watchlist for critical URLs. Inspects up to 10 URLs and returns alert/review/ok assessments without storing state.

Inputs: urls (required), siteUrl, languageCode, continueOnError. Returns: result

gsc_inspect_urlgsc inspect urlB
Read-onlyIdempotent

Inspect a URL for Google indexing status, crawl info, mobile usability, AMP, and rich results. Quota: 2000 requests/day/property.

Inputs: url (required), siteUrl, languageCode. Returns: result

gsc_list_sitemapsgsc list sitemapsA
Read-onlyIdempotent

List sitemaps submitted for a Search Console property, including processing status and submitted/indexed counts.

Inputs: siteUrl, sitemapIndex. Returns: result

gsc_list_sitesgsc list sitesA
Read-onlyIdempotent

List all Google Search Console properties accessible with the current credentials.

Inputs: no named parameters. Returns: result

gsc_monitor_indexation_freshnessgsc monitor indexation freshnessB
Read-onlyIdempotent

Read-only monitoring snapshot for Search Analytics freshness, sitemap indexation totals, and an optional small URL Inspection sample.

Inputs: siteUrl, inspectUrls, searchTypes, languageCode, +2 more. Returns: result

gsc_plan_large_site_samplinggsc plan large site samplingA
Read-onlyIdempotent

Build a read-only URL Inspection sampling plan for large sites from sitemap risk signals and Search Analytics page performance.

Inputs: siteUrl, dateRange, pageLimit, datePreset, +5 more. Returns: result

gsc_query_search_analyticsgsc query search analyticsB
Read-onlyIdempotent

Query Google Search Console Search Analytics. Returns clicks, impressions, CTR, and average position for queries, pages, countries, devices, dates, and search appearances. Use gsc://metrics, gsc://dimensions, gsc://filters, and gsc://compatibility for available fields and rules.

Inputs: limit, filters, metrics, orderBy, +10 more. Returns: result

gsc_track_sitemap_deltasgsc track sitemap deltasA
Read-onlyIdempotent

Read-only sitemap delta tracker. Fetches the current sitemap snapshot and compares it to an agent-provided baseline; no state is written.

Inputs: siteUrl, baseline, includeUnchanged, minAbsIndexedDelta. Returns: result

gsc_validate_querygsc validate queryA
Read-onlyIdempotent

Validate a Search Console metric/dimension/search type combination before executing it.

Inputs: dateRange, dimensions, searchType. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation3/5

    Most tools have distinguishable purposes, but there is notable overlap in the monitoring/health cluster (get_sitemap_health, monitor_indexation_freshness, get_data_freshness, track_sitemap_deltas) and the URL-inspection cluster (inspect_url, bulk_inspect_urls, indexation_watchlist, plan_large_site_sampling). The analytics-derived tools (compare_search_types, find_losses_gains, cluster_queries, detect_cannibalization) also blur together since they all wrap Search Analytics. Descriptions help, but boundaries require careful reading.

    Naming Consistency5/5

    Every tool uses a uniform gsc_ prefix with snake_case and a predictable verb_noun pattern (list_sites, get_site, inspect_url, list_sitemaps, query_search_analytics). No convention mixing or vague one-word names.

    Tool Count3/5

    20 tools is on the heavy side for a read-only Search Console surface. Several tools are thin analytical wrappers or overlapping monitors that could be consolidated, suggesting feature sprawl rather than a tightly scoped set.

    Completeness4/5

    Coverage is broad for a read-only server: sites, analytics, URL inspection, sitemaps, and multiple analytical views. Write operations (sitemap submission, site add/remove) are absent, but these are outside the stated read-only scope, leaving only minor gaps.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Read-only MCP server for Google Search Console data, enabling search analytics, URL inspection, indexing diagnostics, and sitemap management through MCP clients.
      13 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to Google Search Console data, including search analytics, sitemap status, and URL inspection, for MCP clients like Claude.
      9 npm
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Enables local, read-only access to Google Search Console data, allowing users to query site performance, identify ranking opportunities, inspect URL indexing, and review sitemap status through MCP clients.
      8
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to retrieve Search Console search analytics, find multilingual question-shaped queries and SEO opportunities, inspect URLs, and view or manage sitemaps with server-side date resolution and comparisons.
      6
      MIT