@mgcrea/mcp-google-search-console
Read-only Google Search Console integration for search performance analytics (clicks, impressions, CTR, position by date, hour, query, page, country), period-over-period comparisons showing top gainers, losers, new and lost queries or pages, URL Inspection for index status, canonicals, crawl state and rich results (single or up to 20 URLs with quota reporting), and sitemap listing/inspection with optional gated sitemap submit and delete tools. Handles property resolution across URL-prefix and domain properties, reports the signed-in Google account and accessible properties, pages through results, and provides OAuth login/logout plus an escape-hatch request tool limited to the Search Console API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@mgcrea/mcp-google-search-console what dropped in search traffic this week compared to last week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@mgcrea/mcp-google-search-console
A Model Context Protocol server for Google Search Console: search performance (clicks, impressions, CTR, position), period-over-period comparisons, URL Inspection (index status, canonicals, rich results) and sitemaps.
The server is read-only by default. Submitting and deleting sitemaps are not merely refused when writes are off: those tools are never registered, so an agent cannot call them at all.
Features
Property resolution.
siteacceptsexample.com,https://example.com,https://example.com/orsc-domain:example.com, and resolves it against the properties the account can see. A bare domain prefers the domain property; every response says which property was read (site) and, when it was not the exact id you passed, why (resolved_site). An unknown property fails with the list of accessible ones.The account is always visible. The Google account that signed in decides which properties exist. Every response carries
account(its email), and so dogsc_auth_statusand the startup banner.Shaped analytics. Rows come back as
{query, page, clicks, impressions, ctr, position}instead of positionalkeys, with ratios rounded,returned_totals(of the returned rows only), the request echoed, andnext_start_rowfor paging. Dates default to the 28 days ending 3 days ago in Pacific time, Search Console's own day boundary."What dropped?" in one call.
gsc_compare_periodsruns both periods and joins them by key: top gainers, losers, new and lost queries or pages, and each period'sreturned_totals. It fetches 1,000 rows per period by default (depth, up to 5,000).URL Inspection that answers the question. Verdict, coverage, robots/noindex state, last crawl, and
canonical_mismatchwhen Google chose a different canonical than the page declares.gsc_inspect_urlsdoes up to 20 at a time, reportsquota_used, and stops instead of burning quota after a quota error.Remedies, not just errors. 403 permission errors name the signed-in account and how to get access; quota errors explain the right quota (load quota vs. inspection quota) and how long to wait;
invalid_grantexplains the 7-day Testing expiry.
Related MCP server: google-search-console-mcp-server
Security
Read-only by default.
GSC_ALLOW_WRITES=1addsgsc_submit_sitemapandgsc_delete_sitemap(which also requiresconfirm: true), and widensgsc_requestpast GET.Least scope. A read-only install asks only for
webmasters.readonly(plusopenid emailto name the account). Writes ask forwebmasters.Two runtime dependencies: the MCP SDK and Zod. Native
fetchthroughout.Your credentials stay on your machine: the refresh token is stored with mode 600 in
~/.config/google-search-console/tokens.json, and logout revokes it at Google. The API host is fixed (searchconsole.googleapis.com) andgsc_requestonly reaches/webmasters/v3/and/v1/urlInspection/, so the Google token cannot be pointed at another API.Google's Indexing API is deliberately not implemented: Google allows it only for JobPosting and BroadcastEvent pages.
Setup
Search Console needs an OAuth client from a Google Cloud project you own. This takes about five minutes, once.
Create a project. Use a dedicated one, e.g.
mcp-search-console: the consent screen shows its app name.Enable the Google Search Console API.
Configure the consent screen in Google Auth Platform:
Branding: an app name and your email.
Audience: External, then Publish app. While the app is in Testing, Google expires refresh tokens after 7 days. An unverified app in production is fine for your own account; you click past one warning at login.
Go to Clients → Create client and choose application type Desktop app. You don't register a redirect URI, because Desktop clients accept any loopback port.
Set
GSC_CLIENT_IDandGSC_CLIENT_SECRET, and start the server.Ask the agent to call
gsc_auth_login. It opens the consent screen. Sign in with the Google account that has access to your properties in Search Console (an owner can add it under Settings → Users and permissions).
You don't need to restart afterwards.
Configure
Environment first, then ~/.config/google-search-console/config.json (camelCase keys, strict),
field by field.
Variable | Required | Description |
| yes | Desktop-app OAuth client id ( |
| yes | Its secret. Google requires it even with PKCE. |
| no |
|
| no | Use this refresh token (memory only) instead of the token file. |
| no | Where the login is stored. Defaults to |
| no | Config file path. |
| no | Retry budget for 429 / 5xx. Default 3. |
| no | Per-request timeout. Default 30000. |
| no |
|
If you turn writes on after logging in, gsc_auth_status reports the missing scope; log in
again.
A bad setting never stops the server from starting. An out-of-range GSC_MAX_RETRIES (0-10) or
GSC_TIMEOUT_MS (1000-600000) is clamped, and a non-numeric one falls back to its default. A
malformed config file (invalid JSON, an unknown key such as clientID, a wrong type) is ignored
as a whole. Each of these is listed under config_issues in gsc_auth_status and printed to
stderr at startup.
The account email comes from the email claim of the id_token Google returns at login
(and on refresh), not from a separate userinfo call. With GSC_REFRESH_TOKEN, it appears after
the first refresh if that token was granted with openid email; otherwise responses say
account: unknown.
There is deliberately no expected-account setting: every data tool takes an explicit site,
so a login with the wrong Google account fails with "no property matches" and the list of what
that account can see, rather than answering with another tenant's data.
Quotas
From Google's limits page. Quota is free.
Search Analytics: 1,200 queries per minute per property and per user, plus short-term (10-minute) and long-term (daily) load quotas. Grouping or filtering by
pageorquery, and long date ranges, cost the most. When a load quota is exceeded, wait about 15 minutes.URL Inspection: 2,000 inspections per day and 600 per minute, per property.
Everything else (sites, sitemaps): 20 per second and 200 per minute per user.
Search Analytics data lags 2-3 days and is kept for 16 months. Hourly data (hour dimension,
data_state: hourly_all) covers about the last 10 days.
Tools
Tool | What it does | Writes |
| Configured? Signed in? Which account, how many properties, setup steps | no |
| Google consent in the browser, then stores the refresh token | no |
| Revokes the token at Google and deletes it locally | no |
| Properties the account can see: | no |
| Clicks/impressions/CTR/position by date, hour, query, page, country, ... | no |
| Two periods joined by one dimension: gainers, losers, new, lost | no |
| Index status, canonicals, crawl and rich results for one URL | no |
| The same for up to 20 URLs, with | no |
| Submitted sitemaps (or the children of a sitemap index) | no |
| One sitemap's processing status, warnings and errors | no |
| Any | gated |
| Submit or resubmit a sitemap (idempotent) | yes |
| Remove a submitted sitemap, requires | yes |
The read tools are registered as soon as GSC_CLIENT_ID and GSC_CLIENT_SECRET are set, before
login, so gsc_auth_login can complete without a restart.
Things worth knowing
http://,https://,wwwand the trailing slash each make a different URL-prefix property with separate data. A domain property (sc-domain:) covers all of them.A URL with a scheme is never widened to a domain property:
https://shop.example.com/with onlysc-domain:example.comavailable fails and names the domain property, because reading the whole domain would change what the numbers mean. A bareshop.example.comdoes resolve to it, with a note.returned_totalsare the sum of the returned rows, not the property's totals: query-grouped rows omit anonymized queries, and rows are capped byrow_limit.discoverandgoogleNewshave noquerydimension and no position.The sitemap
indexedcount is deprecated by Google and always 0, so it is not returned. Usegsc_inspect_urlfor a page's index status.URL Inspection reports Google's indexed view, not a live test.
A search analytics 429 is not retried: it is almost always the load quota, which clears in about 15 minutes. Other endpoints retry a 429 up to
GSC_MAX_RETRIEStimes.gsc_requestrefuses PUT and DELETE on/webmasters/v3/sitesand/webmasters/v3/sites/{site}(adding or removing a property), even with writes on. Sitemap paths below a property work.
Quick start
pnpm install
pnpm buildThen copy .mcp.json.example to .mcp.json and fill it in.
Inspect the tools
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| node dist/cli.js 2>/dev/null | jq -r '.result.tools[]?.name'Verify live
Everything above is tested against mocked responses only. Nothing has been called against the real API yet. Check these on the first live run:
Login: that the
id_tokencarriesemail, that the granted scope echo is.../auth/userinfo.email, and whether a refresh response also carries anid_token(theGSC_REFRESH_TOKENpath depends on it).searchconsole.googleapis.com/webmasters/v3/...serves the same resources as the documentedwww.googleapis.com/webmasters/v3/....sites.list returns
{siteEntry: [{siteUrl, permissionLevel}]}, and the exactsiteUrlstrings (trailing slash, host case).sitemaps.list returns
{sitemap: [...]}, withwarnings,errorsandsubmittedas int64 strings; whetherindexedis still sent.The error envelope and
reasonfor: a property the account cannot read (assumed 403forbidden), the Search Analytics load quota (assumed 429, which is no longer retried; if it arrives as a 403rateLimitExceededit still is), the URL Inspection daily quota, and an inspection URL outside the property.Whether a 429 carries
Retry-After.hourdimension: the request shape (dimensions: ["hour"],dataState: "hourly_all"), the row key format,metadata.first_incomplete_hour, and how far back it really goes.brandedClassificationandwebMultimodal, which are new (2026) and only documented.A URL Inspection result with rich results and with a Google-chosen canonical, against the shaping, and which errors actually count against the 2,000/day (
quota_usedis an estimate: it counts every call Google answered other than 429, 401 and 403).Whether sites.list returns an internationalised domain as punycode (
xn--…, assumed) or unicode.
Develop
pnpm dev # tsdown --watch
pnpm test # vitest
pnpm typecheck
pnpm lint
pnpm formatPublish
pnpm dlx release-it # bump, commit, tag
git push --follow-tags # CI publishes to npm + GHCR from the tagLicense
MIT
Available Tools
11 toolsgsc_auth_loginSearch Console: LoginAIdempotent
Sign in with Google: opens the consent screen in the browser and waits for it to finish, then stores a refresh token (mode 600) and reports the signed-in account. Pick the Google account that has access to the Search Console properties you want — the account, not any argument, decides which properties are readable. The app is unverified, so Google shows a warning first: Advanced → Go to (app). If no browser can be opened, or the wait runs out, returns the authorize URL instead and keeps listening for 5 minutes; call gsc_auth_status afterwards. Logging in again replaces the stored login.
Inputs: open, wait_seconds.
gsc_auth_logoutSearch Console: LogoutADestructiveIdempotent
Revoke the stored refresh token at Google and delete it locally. Recoverable by calling gsc_auth_login again.
Inputs: no named parameters.
gsc_auth_statusSearch Console: Auth StatusARead-only
Whether the server is configured and signed in, which Google account the token belongs to (the account decides which properties exist at all), how many properties it can read, the granted scopes, whether the write tools are registered, and the quota model. When unconfigured, returns the exact setup steps. Call this first when a tool you expected is missing, a property is not found, or a setting seems to have no effect (config_issues lists values that were clamped or ignored).
Inputs: no named parameters.
gsc_compare_periodsSearch Console: Compare PeriodsARead-only
What changed between two periods, by one dimension: the top gainers and losers present in both, keys that are new or lost, and each period's returned_totals. This is the tool for "what dropped?" or "which pages grew?" — prefer it over two gsc_query_search_analytics calls and diffing them by eye. Defaults: current = the 28 days ending 3 days ago (Pacific), previous = the same-length window just before it. Runs two queries of depth rows each (1,000 by default); by query or page that is the expensive kind of load quota, so do not loop it. returned_totals sum the fetched rows only, not the property: rows past depth are not counted, and by query anonymized queries are missing. When a period fills depth, truncated is set and some new/lost keys may only have crossed the cut.
Inputs: site (required), dimension (required), type, depth, +5 more.
gsc_get_sitemapSearch Console: Get SitemapARead-only
One submitted sitemap's processing status: last submitted and downloaded, pending, whether it is an index, warning and error counts, and submitted URL counts per content type. A 404 means it was never submitted for this property (gsc_list_sitemaps lists those that were).
Inputs: site (required), sitemap_url (required).
gsc_inspect_urlSearch Console: Inspect URLARead-only
Google's index status for one URL, as Search Console's URL Inspection reports it: verdict (PASS / NEUTRAL / FAIL), coverage state (e.g. "Crawled - currently not indexed"), robots.txt and noindex state, last crawl and fetch result, the canonical Google chose versus the one the page declares (canonical_mismatch is true when they differ), sitemaps and referring URLs it knows, and a rich-results summary. This is Google's indexed view, not a live test. QUOTA: 2,000 inspections per day and 600 per minute per property; for several URLs use gsc_inspect_urls.
Inputs: url (required), site (required), language_code.
gsc_inspect_urlsSearch Console: Inspect URLsARead-only
Inspect up to 20 URLs of one property, 3 at a time, with the same per-URL fields as gsc_inspect_url plus a summary (verdicts, canonical mismatches). Prefer this over calling gsc_inspect_url repeatedly — but each URL still costs one of the property's 2,000 daily inspections; quota_used estimates how many were spent. A URL that fails comes back with its own error and remedy instead of failing the call; on a quota, permission or sign-in error the remaining URLs are skipped rather than burned.
Inputs: site (required), urls (required), language_code.
gsc_list_sitemapsSearch Console: List SitemapsARead-only
The sitemaps submitted for a property (or, with sitemap_index, the child sitemaps listed in that index): path, type, last submitted and last downloaded times, whether processing is pending, warning and error counts, and submitted URL counts per content type. Google no longer reports an indexed count here — use gsc_inspect_url for a page's index status.
Inputs: site (required), sitemap_index.
gsc_list_sitesSearch Console: List SitesARead-only
The Search Console properties the signed-in account can see, each with its exact site_url (pass it as site to the other tools), kind and permission_level. A domain property (sc-domain:example.com) covers every protocol and subdomain; a URL-prefix property (https://www.example.com/) covers exactly that scheme, host and path, so http, https and www are separate properties with separate data. siteUnverifiedUser means listed but unreadable. Always fetches fresh; costs one request.
Inputs: no named parameters.
gsc_query_search_analyticsSearch Console: Query Search AnalyticsARead-only
Search performance for a property: clicks, impressions, CTR and average position, grouped by the dimensions you pick (date, hour, query, page, country, device, searchAppearance, brandedClassification). Rows come back with named fields ({query, page, clicks, impressions, ctr, position}), sorted by clicks (by date when grouped by date), plus returned_totals: the sum of the RETURNED rows only, not the property total (rows past row_limit are not counted, and query-grouped rows omit anonymized queries); and next_start_row when there may be more. Dates are Pacific-time calendar days; data lags 2-3 days and is kept 16 months; the default range is the 28 days ending 3 days ago. QUOTA: grouping or filtering by page or query, and long ranges, are the expensive part of the 10-minute and daily load quotas — ask for the dimensions you need, not all of them. The hour dimension needs data_state hourly_all (set for you) and covers only about the last 10 days, which is then the default range. To find what changed between two periods use gsc_compare_periods instead of two queries.
Inputs: site (required), type, filters, end_date, +6 more.
gsc_requestSearch Console: RequestARead-only
Escape hatch: call a Search Console API endpoint that has no dedicated tool. The path must be under /webmasters/v3/ (sites, sitemaps, searchAnalytics) or /v1/urlInspection/, with the property URL-encoded as one segment, e.g. GET /webmasters/v3/sites/sc-domain%3Aexample.com. Returns the raw response, unshaped — prefer the dedicated tools, which resolve the property and name the fields. Writes are DISABLED: only GET is permitted, so the POST-only search analytics and URL inspection endpoints are reachable only through their dedicated tools. Set GSC_ALLOW_WRITES=1 to allow other methods.
Inputs: path (required), body, query, method.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a clearly distinct resource and action: auth status/login/logout, site listing, analytics querying, period comparison, single/batch URL inspection, and sitemap listing/retrieval. The only near-overlaps (gsc_inspect_url vs gsc_inspect_urls, gsc_query_search_analytics vs gsc_compare_periods) are explicitly disambiguated by their descriptions, and gsc_request clearly labels itself as a fallback to be avoided when dedicated tools exist.
All tools use a consistent gsc_ prefix followed by snake_case verb_noun names, e.g. gsc_list_sites, gsc_list_sitemaps, gsc_get_sitemap, gsc_inspect_url. The batch variant gsc_inspect_urls and the auth_* group follow the same predictable convention throughout.
11 tools is well within the typical 3-15 range and each tool maps to a distinct Search Console operation. The auth trio, analytics pair, inspection pair, and sitemaps pair are all justified and no tool feels redundant.
The read-only surface covers authentication, property discovery, search analytics, period comparison, URL inspection, and sitemaps, and gsc_request fills any remaining endpoint gaps. Write operations such as submitting/deleting sitemaps or managing properties are absent, though the server explicitly disables writes by default, making this a minor gap for the intended scope.
Maintenance
Related MCP Connectors
Read-only Search Console analytics, URL inspection, indexing diagnostics, and sitemaps.
Hosted, read-only Google Search Console MCP: performance, comparisons, URL inspection, sitemaps.
Google Search Console for AI assistants: traffic, rankings, indexing and page checks. Read-only.
Read-only Google Search Console and Google Analytics for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Google Search Console data, including search analytics, sitemap status, and URL inspection, for MCP clients like Claude.9 npmMIT
- AlicenseAqualityBmaintenanceEnables MCP clients to query Google Search Console search performance, inspect indexing, analyze sitemaps, and run SEO analyses such as cannibalisation detection, query clustering, and wins/losses, all with read-only access.20Apache 2.0
- AlicenseAqualityBmaintenanceEnables read-only access to Google Search Console data, including property discovery, search analytics queries, and URL inspection, through a security-focused interface.32,636 PyPI2MIT

io.scalably/gsc-mcpofficial
AlicenseAqualityBmaintenanceEnables read-only access to Google Search Console data, including properties, Search Analytics with filters and auto-pagination, sitemaps, and URL inspection with batch support and throttling.564 PyPI1MIT