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

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.

Related MCP server: google-search-console-mcp

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:

~/.config/gws/searchconsole_credentials.json

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.

Scopes: read-only vs. full

• Read tools, including gsc_inspect_url, work with https://www.googleapis.com/auth/webmasters.readonly.

• Write tools (gsc_submit_sitemap, gsc_delete_sitemap) need the full https://www.googleapis.com/auth/webmasters scope.

If your saved credential only has the read-only scope, the read tools work and the write tools return a clear "re-mint with the full scope" error rather than a cryptic 403. Re-running the mint with the full scope upgrades the same file in place; read tools keep working throughout.

Set GSC_CREDENTIALS_PATH to point at a different credential file if you do not use the default location.

Starts without a credential

The server boots and answers tools/list even when no credential is present, so MCP inspectors can introspect it. Tool calls then return a setup pointer (to stderr at startup, and as the tool result). stdout is reserved for the MCP transport and stays clean.

Setup

1. Verify your property in Search Console

Add your site at search.google.com/search-console. A Domain property (verified with a DNS TXT record) covers http/https and all subdomains and is the recommended choice. Note the exact property string — gsc_list_sites will show it as sc-domain:example.com (Domain) or https://example.com/ (URL-prefix).

2. Mint the credential

Create ~/.config/gws/searchconsole_credentials.json as described under Authentication, requesting the full webmasters scope if you want the two sitemap write tools.

3. Configure your MCP client

Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/gsc-mcp"]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/gsc-mcp"]
    }
  }
}

No env block is needed when the credential is at the default path. Set GSC_CREDENTIALS_PATH if it lives elsewhere.

4. Verify

Ask your assistant: "List my Search Console properties," then "Show me striking-distance keywords for it over the last 28 days."

Limitations

Read these so you know what the numbers mean and what this can and cannot do.

• No request-indexing tool — by design. Search Console's "Request indexing" button has no public API. Google's Indexing API only supports JobPosting and BroadcastEvent pages, not normal content, and using it for normal pages violates its terms. So there is deliberately no "ask Google to index this page" tool here; for normal pages, requesting indexing is a manual click in the Search Console UI. gsc_submit_sitemap is the supported, API-backed way to nudge crawling.

• Data lags ~2–3 days. Search Analytics is not real-time. End your date ranges a few days before today or the last days come back empty.

• searchAnalytics is capped per call. row_limit caps at 1000 here (the API allows 25,000 with pagination); for very large pulls, page with start_date/dimension filters rather than asking for everything at once.

• Striking distance is computed client-side. It pulls up to 1000 query rows and filters to the position band. On a site with thousands of ranking queries, the band view reflects the top 1000 by clicks, not the entire long tail.

• URL inspection is rate-limited and slow. Google enforces a low daily quota on the URL Inspection API and each call can take a second or two. Inspect specific URLs you care about; do not loop it over a whole sitemap.

• No property add/remove tools. Verifying a property is a stateful, error-prone flow (DNS TXT, meta tag, file upload) that does not fit a single tool call. Add and verify properties in the Search Console UI; this server operates on properties you have already verified.

• General API quotas apply. The server surfaces a clear error on HTTP 429. Keep row_limit and inspection volume modest.

Development

git clone https://github.com/conorbronsdon/gsc-mcp.git
cd gsc-mcp
npm install
npm run build
npm test

Run locally:

npm start

Tests mock fetch and make no network calls.

Use as a library

The package also exports its tools for embedding, so another MCP server can mount the Search Console tools next to its own instead of running a second process. Importing the package starts nothing and reads no credential.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { DEFAULT_CREDENTIAL_PATH, GSCClient, GoogleAuth, registerGscTools } from "@conorbronsdon/gsc-mcp";

const server = new McpServer({ name: "my-server", version: "1.0.0" });
const auth = GoogleAuth.tryLoad(DEFAULT_CREDENTIAL_PATH);
registerGscTools(server, auth ? new GSCClient(auth) : null);

The mounted tools have the same names, schemas, annotations and results as the standalone server. With a null client they still appear in tools/list and return a setup error when called; pass { credentialPath } as the third argument to name a non-default path in that error.

Contributing

Issues and pull requests are welcome. If a Search Console endpoint is worth wrapping as a tool, open an issue describing what it should return and the endpoint it maps to. Keep the contract honest: read tools stay read-only, write tools carry the right annotations, and responses stay compact.

The rest of the suite

Search Console is one credential family in a wider Google data stack. The siblings, each with its own auth:

Nothing here shares a token: this server uses a webmasters OAuth credential, Workspace uses gws auth login, YouTube Analytics uses a yt-analytics.readonly OAuth credential, GA4 uses Application Default Credentials scoped analytics.readonly.

About

Built and maintained by Conor Bronsdon. I host the Chain of Thought podcast, which covers AI infrastructure, developer tools, and how practitioners actually use this stuff. I built this to pull SEO work into the agent workflows that run the show and my site.

Companion tools:

• op3-mcp: podcast analytics through OP3 — downloads, geography, apps, per-episode breakdowns.

• podcast-benchmark: benchmark your show against peers on public signals.

• Transistor MCP: Transistor.fm's official MCP server. Episodes, publishing, and analytics.

• substack-mcp: read posts and manage drafts on Substack, safe for agent workflows.

• ai-tools-for-creators: a curated list of AI skills and MCP servers for people who ship ideas for a living.

More at chainofthought.show and on X.

Disclaimer

This is an independent personal project, not affiliated with, sponsored by, or endorsed by Google LLC. All views expressed are my own.

License

MIT