I wanted to analyze Google Search Console data without jumping between GSC, spreadsheets, and my codebase.
So I connected GSC to Claude Code using Amin Forou's open-source mcp-gsc server.
Now I can ask:
Claude retrieves the relevant data, analyzes it alongside my code, and helps me decide what to change.
Claude Code
↓ MCP over stdio
mcp-gsc running locally
↓ OAuth 2.0
Google Search Console API
The MCP server converts Search Console operations into tools Claude can call. It supports performance analysis, URL inspection, sitemap management, period comparisons, and property discovery.
I used OAuth so the server could access the same GSC properties as my Google account.
Open the Google Cloud Console and create a dedicated project.
Then:
The authorized Google account must already have access to the Search Console property.
The server requests this scope:
https://www.googleapis.com/auth/webmasters
This is the read/write Search Console scope. Destructive mcp-gsc operations remain disabled unless GSC_ALLOW_DESTRUCTIVE=true
is explicitly set.
Important: for an external app in Testing, Google normally expires the authorization and refresh token after seven days. If authentication suddenly stops, run the reauthentication tool and approve access again.
In Google Auth Platform → Clients:
Example:
/Users/yourname/Documents/credentials/gsc-client-secrets.json
Never commit this file to Git.
The simplest method uses uvx
, which runs the package in an isolated Python environment.
Install uv
using its official installation guide, then verify it:
uv --version
uvx --version
which uvx
Keep the full path returned by which uvx
. Claude Code may not inherit your terminal's PATH
, so using only uvx
can cause a spawn uvx ENOENT
error.
Replace the example paths with absolute paths from your machine:
claude mcp add-json --scope user gscServer '{
"type": "stdio",
"command": "/Users/yourname/.local/bin/uvx",
"args": ["mcp-search-console"],
"env": {
"GSC_OAUTH_CLIENT_SECRETS_FILE": "/Users/yourname/Documents/credentials/gsc-client-secrets.json"
}
}'
I used user scope so the integration was available across my local projects without committing credential paths to a repository.
Verify the configuration:
claude mcp list
claude mcp get gscServer
Start Claude Code and ask:
Call the GSC get_capabilities tool and report the authentication status.
The first request opens Google's OAuth flow in your browser. Sign in with the test-user account and approve access.
Then ask:
List every Search Console property I can access and show its exact identifier.
Use the identifier returned by the API. Search Console has two formats:
Domain property: sc-domain:example.com
URL-prefix property: https://www.example.com/
The protocol, hostname, and trailing slash must match exactly for URL-prefix properties.
The server exposes tools including:
get_performance_overview
get_search_analytics
get_advanced_search_analytics
compare_search_periods
get_search_by_page_query
inspect_url_enhanced
batch_url_inspection
check_indexing_issues
list_sitemaps_enhanced
reauthenticate
For recent dashboard-like data, keep the default GSC_DATA_STATE=all
. For stable reporting with a short delay, use GSC_DATA_STATE=final
.
For sc-domain:example.com, find non-branded queries with at least 500 impressions and positions from 11 to 20 in the last 28 days. Group them by ranking page and recommend whether to update an existing page or create a new one.
Find pages ranking in positions 1 to 10 with at least 1,000 impressions and CTR below 2%. Show their leading queries and suggest accurate title improvements.
Compare the latest 28 complete days with the previous 28 days. Separate changes caused by impressions, CTR, and position. Show the ten biggest winning and losing pages.
Inspect the ten highest-click landing pages. Flag canonical mismatches, robots restrictions, crawl failures, and pages missing from Google's index.
Authentication fails after seven days: Your external OAuth app is still in Testing. Call reauthenticate
and approve access again.
** spawn uvx ENOENT:** Use the complete path returned by
which uvx
.Credentials file not found: Use an absolute path in GSC_OAUTH_CLIENT_SECRETS_FILE
.
Property returns 404: Run list_properties
and copy the exact sc-domain:
or URL-prefix value.
No MCP tools appear: Check claude mcp list
. Manual repository installations also require Python 3.11 or newer.
My SEO workflow changed from:
GSC → CSV export → spreadsheet → codebase
to:
Search data → opportunity → page → code change → measurement
The biggest benefit is not generating more SEO content. It is giving the coding assistant real search data so it can investigate the correct page before making a change.
Disclosure: I used AI to help edit this article. The setup is based on my own implementation and was manually verified.