MCP Google Search Console
Secure MCP server for Google Search Console analytics, sitemaps, and URL inspection
Ask AI about MCP Google Search Console
Powered by Claude Β· Grounded in docs
I know everything about MCP Google Search Console. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
mcp-google-search-console-crunchtools
Secure MCP server for Google Search Console. Query search analytics (clicks, impressions, CTR, position), manage sitemaps, inspect URL indexing status, and manage site properties.
Installation
uvx (recommended, zero-install)
claude mcp add mcp-google-search-console-crunchtools \
--env GSC_CLIENT_ID=your_client_id \
--env GSC_CLIENT_SECRET=your_client_secret \
--env GSC_REFRESH_TOKEN=your_refresh_token \
-- uvx mcp-google-search-console-crunchtools
pip
pip install mcp-google-search-console-crunchtools
Container (Podman/Docker)
podman run -d -p 8017:8017 \
--env-file ~/.config/mcp-env/mcp-google-search-console.env \
quay.io/crunchtools/mcp-google-search-console \
--transport streamable-http --host 0.0.0.0
OAuth Setup
This server authenticates to Google using OAuth2 with a refresh token. This is a one-time setup β once you have the three credentials, you store them as environment variables and never need to touch OAuth again.
What you need
| Credential | What it is | Where it comes from |
|---|---|---|
GSC_CLIENT_ID | Identifies your OAuth app to Google | Google Cloud Console |
GSC_CLIENT_SECRET | Secret key for your OAuth app | Google Cloud Console |
GSC_REFRESH_TOKEN | Long-lived token that lets the server get access tokens | One-time browser consent flow |
Step 1: Create a Google Cloud OAuth App
- Go to Google Cloud Console
- Create a new project (or select an existing one)
- Navigate to APIs & Services > Library
- Search for Google Search Console API and click Enable
- Navigate to APIs & Services > Credentials
- Click + CREATE CREDENTIALS > OAuth client ID
- If prompted, configure the OAuth consent screen first:
- User type: External (or Internal if using Google Workspace)
- App name: anything (e.g., "MCP Search Console")
- Scopes: add
https://www.googleapis.com/auth/webmasters - Test users: add your Google account email
- Back on Create OAuth client ID:
- Application type: Desktop app
- Name: anything (e.g., "MCP Search Console Desktop")
- Click Create β copy the Client ID and Client Secret
Step 2: Get a Refresh Token
Run this in your terminal to start the consent flow:
# Set your credentials from Step 1
export GSC_CLIENT_ID="your_client_id_here"
export GSC_CLIENT_SECRET="your_client_secret_here"
# Generate the authorization URL
echo "Open this URL in your browser:"
echo ""
echo "https://accounts.google.com/o/oauth2/v2/auth?client_id=${GSC_CLIENT_ID}&redirect_uri=http://127.0.0.1&response_type=code&scope=https://www.googleapis.com/auth/webmasters&access_type=offline&prompt=consent"
- Open the printed URL in your browser
- Sign in with the Google account that owns your Search Console properties
- Click Allow to grant Search Console access
- The browser will redirect to
http://127.0.0.1/?code=XXXX&scope=... - This page will fail to load β that's expected. Copy the
code=value from the URL bar (everything betweencode=and&scope)
Now exchange the authorization code for a refresh token:
# Paste the code value from the URL bar (the part between code= and &scope)
AUTH_CODE="paste_your_code_here"
curl -s -X POST https://oauth2.googleapis.com/token \
-d "client_id=${GSC_CLIENT_ID}" \
-d "client_secret=${GSC_CLIENT_SECRET}" \
-d "code=${AUTH_CODE}" \
-d "grant_type=authorization_code" \
-d "redirect_uri=http://127.0.0.1" | python3 -m json.tool
The response will include a refresh_token field β copy it. This is the long-lived credential that lets the server authenticate without a browser.
Note: If you don't see
refresh_tokenin the response, add&prompt=consentto the authorization URL and try again. Google only returns the refresh token on the first consent or when explicitly prompted.
Step 3: Store the Credentials
Create an env file:
cat > ~/.config/mcp-env/mcp-google-search-console.env << 'EOF'
GSC_CLIENT_ID=your_client_id
GSC_CLIENT_SECRET=your_client_secret
GSC_REFRESH_TOKEN=your_refresh_token
EOF
chmod 600 ~/.config/mcp-env/mcp-google-search-console.env
How it works at runtime
The server never stores or manages tokens on disk. On each API call:
- Server sends the refresh token to Google's token endpoint
- Google returns a short-lived access token (valid ~1 hour)
- Server uses the access token for the Search Console API call
- Access tokens are cached in memory and refreshed automatically when they expire
The refresh token itself never expires unless you explicitly revoke it in your Google Account permissions.
Available Tools (10)
| Category | Count | Tools |
|---|---|---|
| Sites | 4 | list_sites, get_site, add_site, delete_site |
| Search Analytics | 1 | query_search_analytics |
| Sitemaps | 4 | list_sitemaps, get_sitemap, submit_sitemap, delete_sitemap |
| URL Inspection | 1 | inspect_url |
Security
- OAuth2 credentials stored as
SecretStr(never logged) - Environment-variable-only credential storage
- Automatic token scrubbing from error messages
- Pydantic input validation with
extra="forbid" - No filesystem access, shell execution, or code evaluation
- TLS certificate validation (httpx default)
- Request timeouts and response size limits
- Built on Hummingbird container images
See SECURITY.md for the full security design document.
Development
uv sync --all-extras
uv run ruff check src tests
uv run mypy src
uv run pytest -v
gourmand --full .
podman build -f Containerfile .
