conorbronsdon/gsc-mcp

> **Maintenance mode.** This project is stable and receives security fixes. New features aren't planned, but issues and pull requests are still welcome.
Google Search Console for AI agents: search performance, striking-distance keywords, sitemaps, and URL inspection. SEO automation you can hand to an assistant.
---
An MCP server for Google Search Console. It gives an AI assistant the data and the levers behind organic search: how queries and pages perform, which keywords are one nudge away from page one, the state of your sitemaps, and whether a specific URL is indexed — plus the ability to submit or remove sitemaps.
**Why this exists.** Search Console is where SEO actually happens, but its UI is click-heavy and its data is hard to act on at a glance. The single most useful view — queries ranking in *striking distance* of page one — is not even a built-in report; you have to filter and eyeball it. This server puts that view, and the rest of the funnel, in front of an agent so the boring parts of SEO (find the near-miss keywords, check index status, keep sitemaps healthy) can be automated.
It was built to run SEO for two sites — a podcast and a personal site — but nothing here is specific to them. Point it at any property you have verified.
Tools
| Tool | Access | What it returns | API |
|------|--------|-----------------|-----|
| gsc_list_sites | read | Verified properties + permission level | GET webmasters/v3/sites |
| gsc_search_analytics | read | Clicks/impressions/CTR/position by query, page, country, device, or date | POST .../searchAnalytics/query |
| gsc_striking_distance | read | Queries at avg position 8–25 with enough impressions — the optimization list | computed from search analytics |
| gsc_list_sitemaps | read | Submitted sitemaps with status, last download, warning/error counts | GET .../sitemaps |
| gsc_submit_sitemap | **write** | Submits/pings a sitemap to Google | PUT .../sitemaps/{feedpath} |
| gsc_delete_sitemap | **write, destructive** | Deregisters a sitemap from Search Console | DELETE .../sitemaps/{feedpath} |
| gsc_inspect_url | read | Index status, last crawl, canonical, mobile/rich-results verdicts | POST searchconsole/v1/urlInspection/index:inspect |
Every tool carries MCP read/write annotations, so a client can tell the two write tools apart from the five read-only ones before calling them. Read tools are readOnlyHint: true; gsc_submit_sitemap is a non-destructive write; gsc_delete_sitemap is destructiveHint: true.
List tools default row_limit / limit low (25) to keep responses small — agents pay tokens per response.
Authentication
This server uses an OAuth **installed-app** credential (a saved refresh token), not a service account or an API key. It reads the credential from:
The file is google-auth's Credentials.to_json() shape: it contains client_id, client_secret, refresh_token, and scopes. The server refreshes short-lived access tokens against Google's token endpoint directly with fetch — no heavy googleapis dependency.
To create the file yourself if you do not already have it:
1. In Google Cloud Console, create an **OAuth client** of type *Desktop app* and download its client_secret.json.
2. Enable the **Search Console API** on that project.
3. Run an installed-app OAuth flow requesting the scope you need (see below) and save the resulting credentials to ~/.config/gws/searchconsole_credentials.json. Any standard google-auth-oauthlib installed-app snippet works — about ten lines, and it opens a browser for a single consent click.
The path is shared on purpose: if you already hold a Search Console credential in that location for other tooling, this server reuses it rather than asking you to mint a second one.