acamolese/google-search-console-mcp

**English** · Italiano
Seventeen read-only tools over the Google Search Console API, plus a deterministic
white-label HTML audit report an agency can put its own name on and send to a
client, in English or Italian.
Regenerate that report from committed synthetic data, with no credentials:
Install
Claude Code
The plugin brings the MCP server, five skills (weekly review, cannibalisation
check, indexing audit, content opportunities, white-label client audit) and a
config prompt for the three credentials.
Claude Desktop
Download google-search-console.mcpb from the
latest release
and open it. It needs uv installed. Or edit the
config file directly:
Cursor, Codex, Gemini CLI, Zed
Any MCP client takes the same three lines: command uvx, argument
mcp-google-search-console, and the three GSC_* environment variables.
Docker
The container speaks streamable HTTP on /mcp. It has no authentication of its
own: keep it on loopback or behind a reverse proxy.
Authentication
The OAuth scope is webmasters.readonly and nothing else. No tool in this server
can modify a property, a sitemap or anything else in Search Console.
Credentials are resolved in this order:
1. GSC_AUTH_MODE if set (oauth, service_account, adc)
2. GSC_SERVICE_ACCOUNT_FILE or GSC_SERVICE_ACCOUNT_JSON
3. GSC_CLIENT_ID + GSC_CLIENT_SECRET + GSC_REFRESH_TOKEN
4. A token file in ~/.config/mcp-google-search-console/
5. Application Default Credentials
OAuth, once
1. In Google Cloud Console, enable the
**Google Search Console API** and create an OAuth client of type
**Desktop app**.
2. Export the client, or save the downloaded JSON as
~/.config/mcp-google-search-console/oauth_credentials.json:
3. The browser flow prints the three export lines for a stateless setup, and
also stores a token at ~/.config/mcp-google-search-console/token.json with
0600 permissions.
On a headless machine, run auth on your laptop and copy the three environment
variables across. --no-browser prints the URL instead of opening one, but still
needs a local redirect.
Service account
Grant the service account's email read access to the property in Search Console,
then point the server at the key:
Check it works
Prints the auth mode in use, when the token expires, how many properties the
account can read, and the defaults every tool applies. Secrets are masked. Exits
1 when nothing resolves, which is the answer to most "the server won't start"
reports.
Tools
| Tool | What it answers |
|---|---|
| gsc_sites | Which properties can this account read, and in what exact format |
| gsc_site_details | Permission level and type for one property |
| gsc_query | The Search Analytics report, with filters, dimensions and pagination |
| gsc_performance_overview | Is the site up or down, against the previous period |
| gsc_compare_periods | What changed between two periods, ranked by click delta |
| gsc_quick_wins | Queries close enough to the top that a push would pay off |
| gsc_ctr_gaps | Pages that rank but are not clicked |
| gsc_cannibalization | Queries where several pages compete against each other |
| gsc_traffic_drops | Pages that lost clicks, with a likely cause for each |
| gsc_content_decay | Pages sliding down month after month |
| gsc_alerts | What moved sharply enough to be worth a message today |
| gsc_portfolio | Every property at a glance, worst first |
| gsc_indexing_issues | Which of these URLs are indexed, and why not |
| gsc_inspect_url | Full URL Inspection for one page |
| gsc_sitemaps | Which sitemaps Google knows about, with errors and warnings |
| gsc_doctor | What is configured, and does the API answer |