Google Search Console MCP Server
Provides tools for interacting with the Google Search Console API v1, covering all published methods and task-shaped tools for property/site management, sitemaps, search performance analytics, URL inspection, and URL testing.
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., "@Google Search Console MCP Server what are my top search queries for example.com in the last 28 days?"
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.
Google Search Console MCP Server
An MCP server covering the entire Google Search Console API — all 11 published methods, plus task-shaped tools on top for the questions people actually ask of search performance data.
Overview
This project provides a Model Context Protocol server that wraps the Google Search Console API v1, letting LLMs work with search performance data, sitemaps, property management and URL indexing through a standardised interface.
Search Console ships no official SDK in any language, so this is built on the
generic google-api-python-client with complete static types supplied by
google-api-python-client-stubs. See
Why there is no Search Console SDK.
Related MCP server: Google Search Console MCP Server
Features
Complete API Coverage: all 11 published API methods, enforced by a test rather than claimed
Full Type Safety: strict
pyrightwith 0 errors100% Test Coverage: 144 tests, 100% statement and branch coverage, floor enforced in config
Task-Shaped Tools: 11 convenience tools on top of the raw API
MCP Compliant: FastMCP 4, stdio transport
Async Throughout: the synchronous Google client is dispatched off the event loop
Read-Only Mode: an opt-in switch that refuses every mutating call
Installation
git clone https://github.com/rgellis/google-search-console-mcp.git
cd google-search-console-mcp
# Install dependencies using uv
uv syncRequires Python 3.12+.
1. Enable the API
Search Console API must be enabled on the Google Cloud project that owns your OAuth client:
gcloud services enable searchconsole.googleapis.com --project=<project>2. Create an OAuth client
In the Google Cloud console, create an OAuth 2.0 client of type Desktop app
(or Web application with http://localhost as an authorised redirect URI).
Note the client ID and secret.
3. Mint a refresh token
Search Console needs the https://www.googleapis.com/auth/webmasters scope:
GOOGLE_CLIENT_ID="..." GOOGLE_CLIENT_SECRET="..." \
uv run scripts/get_refresh_token.py
# or, if this server will never manage properties:
GOOGLE_CLIENT_ID="..." GOOGLE_CLIENT_SECRET="..." \
uv run scripts/get_refresh_token.py --read-onlySign in as an account with access to the Search Console properties you need. The script prints the refresh token.
Scope the token to this server alone rather than reusing one minted for other
Google APIs — re-consenting a shared token to add webmasters rotates a secret
everything else using it depends on.
4. Set credentials
export GOOGLE_CLIENT_ID="your_client_id"
export GOOGLE_CLIENT_SECRET="your_client_secret"
export GOOGLE_SEARCH_CONSOLE_REFRESH_TOKEN="token_from_step_3"
# optional: request only the readonly scope and refuse all mutations
export SEARCH_CONSOLE_READ_ONLY=falseIf those three are not all set, the client falls back to Application Default
Credentials, which covers a service account via GOOGLE_APPLICATION_CREDENTIALS
as well as local gcloud auth.
5. Verify
uv run main.py --groups sitesThen call check_client_status, which reports whether credentials resolve, the
scopes in use, and whether read-only mode is active — without spending API quota.
Usage
uv run main.py # all tools, over stdio
uv run main.py --groups sites,analytics # a subsetGroups: sites, sitemaps, analytics, inspection, testing-tools.
With an MCP client
{
"mcpServers": {
"search-console": {
"command": "uv",
"args": ["run", "--directory", "/path/to/google-search-console-mcp", "main.py"],
"env": {
"GOOGLE_CLIENT_ID": "...",
"GOOGLE_CLIENT_SECRET": "...",
"GOOGLE_SEARCH_CONSOLE_REFRESH_TOKEN": "..."
}
}
}
}Property identifiers
Search Console has two property types and the API is strict about the exact string for each. Tools normalise input, so all of these work:
You pass | Sent to the API |
|
|
|
|
|
|
|
|
A URL-prefix property passed without its trailing slash is the most common cause of a spurious 403 from this API, which is why normalisation happens here rather than being left to the caller. A 403 raised by this server appends a reminder of exactly that.
Feature Parity Table
Implementation status of Google Search Console API v1 methods (discovery revision 20260909):
Tool | Category | API Method | Implemented | Test Coverage | Notes |
Property Management | |||||
| Sites |
| ✅ Yes | ✅ Yes | All properties and permission levels |
| Sites |
| ✅ Yes | ✅ Yes | One property, with permission level |
| Sites |
| ✅ Yes | ✅ Yes | Mutation; needs verification afterwards |
| Sites |
| ✅ Yes | ✅ Yes | Mutation; irreversible via the API |
Sitemaps | |||||
| Sitemaps |
| ✅ Yes | ✅ Yes | Optional sitemap-index drill-down |
| Sitemaps |
| ✅ Yes | ✅ Yes | Processing status and error counts |
| Sitemaps |
| ✅ Yes | ✅ Yes | Mutation |
| Sitemaps |
| ✅ Yes | ✅ Yes | Mutation |
| Sitemaps | (composes | ✅ Yes | ✅ Yes | Bulk; failure-tolerant per sitemap |
Search Analytics | |||||
| Search Analytics |
| ✅ Yes | ✅ Yes | Raw 1:1 wrapper, full request control |
| Search Analytics | (composes | ✅ Yes | ✅ Yes | Pages past the 25,000-row cap |
| Search Analytics | (grouped by | ✅ Yes | ✅ Yes | Sorted by clicks, named fields |
| Search Analytics | (grouped by | ✅ Yes | ✅ Yes | Sorted by clicks |
| Search Analytics | (grouped by | ✅ Yes | ✅ Yes | Daily time series |
| Search Analytics | (grouped by | ✅ Yes | ✅ Yes | ISO-3166-1 alpha-3 |
| Search Analytics | (grouped by | ✅ Yes | ✅ Yes | Desktop / mobile / tablet |
| Search Analytics | (grouped by | ✅ Yes | ✅ Yes | Rich result types |
| Search Analytics | (two queries, with deltas) | ✅ Yes | ✅ Yes | Equal-length preceding period, flags new |
URL Inspection | |||||
| URL Inspection |
| ✅ Yes | ✅ Yes | Index status, canonicals, crawl, AMP |
| URL Inspection | (composes | ✅ Yes | ✅ Yes | Bulk, quota-aware, verdict summary |
URL Testing Tools | |||||
| Testing Tools |
| ✅ Yes | ✅ Yes | ⚠️ Shut down by Google 1 Dec 2023 |
Diagnostics | |||||
| Diagnostics | (no API call) | ✅ Yes | ✅ Yes | Credential state; spends no quota |
Summary Statistics
API Methods Implemented: 11 out of 11 Search Console API v1 methods (100%)
Total Tools: 22 (11 API methods + 11 convenience tools)
Tools with Tests: 22 (100% test coverage)
Line & Branch Coverage: 100% across
src(468 statements, 96 branches), enforced byfail_under = 100Test Count: 144
Type Safety:
pyrightstrict, 0 errors
Implementation Highlights
✅ Complete API Surface: every published method, including the one Google deprecated
✅ Coverage Enforced, Not Claimed:
tests/test_api_coverage.pydiffs the implementation against the vendored discovery document in both directions✅ End-to-End Tool Tests: every tool is invoked through a real MCP client, not just unit-tested at the service layer
✅ Correct Metric Aggregation: totals recompute CTR from summed clicks/impressions and weight position by impressions — averaging either across rows gives a wrong answer
✅ Quota Awareness: bulk URL inspection refuses to exceed the documented 2,000/property/day limit
Key Features
Typed Discovery Client: complete static types from
google-api-python-client-stubsOff-Loop Execution: the synchronous Google client is dispatched via
asyncio.to_thread, so it never blocks the MCP event loopUniform Error Translation: one
execute()helper turnsHttpErrorinto a readable message, including a 403 hint about property-identifier formatLazy Client Initialisation: credentials resolve on first use, so the server starts even when misconfigured and
check_client_statuscan say whyRead-Only Mode:
SEARCH_CONSOLE_READ_ONLY=truerequests the readonly scope and refuses all four mutationsProperty Normalisation: domain vs URL-prefix properties handled at the boundary
Deprecated API Methods
Nothing is unimplemented. One method is implemented but non-functional upstream:
urlTestingTools.mobileFriendlyTest.run— Google shut this down on 1 December 2023. It is still published in the discovery document, so it is implemented here for complete coverage, and its docstring says plainly that it returns an error. For mobile usability signals useinspect_url, whose response carries amobileUsabilityResult.
Why there is no Search Console SDK
Search Console is a discovery-document API. Google ships no dedicated client
library for it in any language — no equivalent of google-ads or
google-analytics-data. It is one of ~300 APIs served by the generic
google-api-python-client, whose resources are built dynamically at runtime and
are entirely untyped.
Other languages fare better, because their generic clients generate code at build
time into per-API packages: Go has google.golang.org/api/searchconsole/v1, Java
has google-api-services-searchconsole, .NET has Google.Apis.SearchConsole.v1,
and Node's googleapis ships Schema$* TypeScript interfaces. Python is the
outlier — its client parses the discovery document at runtime, so there is
nothing to type-check.
That would normally rule out strict type checking. The way out is
google-api-python-client-stubs, which covers searchconsole/v1 completely: all
30 schemas as TypedDicts with Literal enums, and a build() overload keyed on
the literal service name. It is a dev-only dependency — stubs never ship at
runtime, so if it goes stale the cost is type-checking, not functionality.
Two consequences to know before editing:
src/client.pyimportsSearchConsoleResourceunderif TYPE_CHECKING:. Thegoogleapiclient._apispackage does not exist at runtime; that guard must stay.FastMCP resolves tool annotations at runtime, so tool signatures use
Dict[str, Any]while the service layer beneath stays precisely typed. Annotating a tool with a stub type raisesNameErrorat registration.
Testing
# Run tests
uv run pytest
# Run tests with coverage (must stay at 100%)
.venv/bin/python -m pytest --cov --cov-report=term-missing
# Run type checking
uv run pyright
# Run code formatting
uv run ruff format .
# Everything at once
./scripts/typecheck.shCoverage is invoked as .venv/bin/python -m pytest rather than uv run pytest
for one reason, documented in pyproject.toml: constructing a FastMCP instance
inside a coverage-instrumented module trips a type check in cryptography's Rust
bindings, so main.py is excluded from the measured source set and covered
end-to-end by tests/test_api_coverage.py instead.
Test layout
File | Covers |
| Every tool invoked through a real MCP client, end to end |
| Sites service methods |
| Sitemaps service methods |
| Query building, pagination, aggregation maths, period comparison |
| Inspection, bulk summarising, quota guard |
| Deprecated Mobile-Friendly Test |
| Credential resolution, scopes, read-only gate, lifecycle |
| Error translation, 403 hint, off-loop dispatch |
| Property normalisation, date maths, dotenv |
| The API coverage contract, both directions |
When Google revises the API
uv run scripts/refresh_discovery.py
uv run pytest tests/test_api_coverage.pyA new method fails test_every_api_method_is_declared until it is implemented
and mapped in src/coverage.py. A removed one fails
test_no_declared_method_has_been_removed. That failure is the intended alarm —
do not weaken the test.
Repository layout
src/client.py credentials, typed discovery client, read-only gate
src/coverage.py API method -> tool mapping; the coverage contract
src/services/ one module per API resource
src/services/base.py off-loop dispatch and error translation
refs/ vendored discovery document
scripts/ token minting, discovery refresh, checks
tests/ 144 tests, 100% coverage
main.py stdio MCP serverContributing
Contributions are welcome. Please ensure:
All code has proper type annotations
Tests are added for new functionality — coverage must stay at 100%
Code passes
uv run pyrightwith no errorsCode is formatted with
uv run ruff formatAny new API method is mapped in
src/coverage.py
License
MIT — see LICENSE.
Disclaimer
This is an unofficial integration and is not affiliated with or endorsed by Google. Search Console API quotas apply; the URL Inspection API is limited to 2,000 queries per property per day and 600 per minute.
Available Tools
22 toolsadd_siteAdd SiteA
Add a property to Search Console. Requires verification afterwards.
Inputs: site_url (required). Returns: object
check_client_statusCheck Client StatusA
Check that the Search Console client is configured and can authenticate.
Returns: Whether credentials resolve, whether the server is in read-only mode, and the OAuth scopes in use.
Inputs: no named parameters. Returns: object
compare_periodsCompare PeriodsB
Compare a period against the equal-length period immediately before it.
Inputs: site_url (required), filters, end_date, dimension, +3 more. Returns: object
delete_siteDelete SiteA
Remove a property from Search Console.
This unlinks the property from the account. Historical data is retained by Google but becomes inaccessible until the property is re-added and re-verified.
Inputs: site_url (required). Returns: object
delete_sitemapDelete SitemapC
Delete a sitemap from Search Console.
Inputs: feedpath (required), site_url (required). Returns: object
get_siteGet SiteB
Get one Search Console property and the caller's permission level.
Inputs: site_url (required). Returns: object
get_sitemapGet SitemapA
Get one sitemap's processing status and error counts.
Inputs: feedpath (required), site_url (required). Returns: object
inspect_urlInspect UrlA
Inspect one URL's index status in Google Search.
Inputs: site_url (required), inspection_url (required), language_code. Returns: object
inspect_urlsInspect UrlsA
Inspect several URLs and summarise their index status.
Each URL costs one unit of the 2,000-per-property-per-day URL Inspection quota.
Inputs: site_url (required), inspection_urls (required), language_code. Returns: object
list_sitemapsList SitemapsC
List the sitemaps submitted for a property.
Inputs: site_url (required), sitemap_index. Returns: object
list_sitesList SitesA
List all Search Console properties the account can access.
Returns: Each property's siteUrl and the caller's permissionLevel (siteOwner, siteFullUser, siteRestrictedUser or siteUnverifiedUser).
Inputs: no named parameters. Returns: object
performance_by_countryPerformance By CountryC
Performance broken down by country.
Inputs: site_url (required), filters, end_date, row_limit, +2 more. Returns: object
performance_by_datePerformance By DateC
Daily performance time series for a property.
Inputs: site_url (required), filters, end_date, row_limit, +2 more. Returns: object
performance_by_devicePerformance By DeviceB
Performance broken down by device (desktop, mobile, tablet).
Inputs: site_url (required), filters, end_date, start_date, +1 more. Returns: object
performance_by_search_appearancePerformance By Search AppearanceA
Performance broken down by search appearance (rich result types).
Note that SEARCH_APPEARANCE cannot be combined with other dimensions in the same request, which is why this has no filters argument.
Inputs: site_url (required), end_date, row_limit, start_date, +1 more. Returns: object
query_all_rowsQuery All RowsB
Retrieve every row for a query, paging past the 25,000-row cap.
Inputs: end_date (required), site_url (required), start_date (required), filters, +4 more. Returns: object
query_search_analyticsQuery Search AnalyticsA
Run a raw Search Analytics query with full control over the request.
This is the unmodified API method. For the common cases prefer top_queries, top_pages, performance_by_date, performance_by_country, performance_by_device, compare_periods or query_all_rows.
Inputs: end_date (required), site_url (required), start_date (required), row_limit, +6 more. Returns: object
run_mobile_friendly_testRun Mobile Friendly TestA
DEPRECATED AND NON-FUNCTIONAL. Run the Mobile-Friendly Test on a URL.
Google shut this API down on 1 December 2023; calling it returns an error. It exists here only so this server covers the published API surface completely. Do not call it expecting a result. For mobile usability signals, use inspect_url instead, whose response carries a mobileUsabilityResult.
Inputs: url (required), request_screenshot. Returns: object
submit_sitemapSubmit SitemapC
Submit a sitemap to Search Console.
Inputs: feedpath (required), site_url (required). Returns: object
submit_sitemapsSubmit SitemapsB
Submit several sitemaps to one property in a single call.
Inputs: site_url (required), feedpaths (required). Returns: result
top_pagesTop PagesC
Top landing pages by clicks for a property.
Inputs: site_url (required), filters, end_date, row_limit, +2 more. Returns: object
top_queriesTop QueriesC
Top search queries by clicks for a property.
Inputs: site_url (required), filters, end_date, row_limit, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Most tools target distinct resources or actions, and descriptions explicitly differentiate the raw analytics query from specialized ones. Minor overlap exists between singular/plural pairs (submit_sitemap/submit_sitemaps, inspect_url/inspect_urls), but the text clarifies the distinction.
Names are consistently snake_case and mostly follow a verb_noun pattern. A few analytics tools are noun phrases (top_queries, performance_by_date), which is a minor deviation but still readable and coherent.
At 22 tools the set feels heavy for the domain. Several analytics wrappers overlap with query_search_analytics, and run_mobile_friendly_test is explicitly deprecated and non-functional, so not every tool earns its place.
The surface covers full lifecycle operations for sites and sitemaps, offers comprehensive search analytics breakdowns, and includes both single and batch URL inspection. No obvious gaps remain for the Google Search Console API.
Maintenance
Related MCP Connectors
Google Search Console for AI assistants: traffic, rankings, indexing and page checks. Read-only.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Read-only Google Search Console and Google Analytics for AI agents.
Google Search Console in your AI: overview, opportunities, index gaps, page checks, long history.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interacting with Google Search Console via natural language, supporting search analytics, URL inspection, sitemap management, and site listing.25-
- AlicenseAqualityDmaintenanceConnects Google Search Console to AI assistants, enabling natural language analysis of SEO data. Provides read-only tools for properties, search analytics, URL inspection, and sitemaps.15MIT
- AlicenseAqualityBmaintenanceEnables AI agents to query and analyze Google Search Console data, including search analytics, URL inspection, sitemaps, and property verification, and to perform actions like submitting sitemaps and adding properties through natural language.1924 npm1MIT
- FlicenseNot gradedqualityCmaintenanceEnables Claude to query Google Search Console data, including search analytics, sitemaps, URL inspection, and page indexing audits.-