Google Search Console

Google Search Console MCP Server

[CI] [PyPI] [Python] [License: MIT]

A local Model Context Protocol server that connects AI assistants (Claude Code, Claude Desktop, Cursor and any other MCP client) to the Google Search Console API. Ask about clicks, queries, pages, indexing and sitemaps in plain language; the server turns that into correct API calls and returns structured data.

It runs on your machine and talks to Google; the only other site it reads is your own, during an indexing audit. It stores your login and your audits' progress, nothing else.

Unofficial. This project is not affiliated with or endorsed by Google. You use your own Google Cloud credentials and are responsible for your usage under Google's terms.

Why this one

• It catches the API's traps. Google answers many bad requests with an empty result instead of an error: an invalid regex, a two-letter country code, hourly data older than ten days, a range in the future. Other combinations fail with a terse 400. Every one of these is checked before the call and explained in plain words. The rules are verified against the live API, not copied from blog posts.
• It explains changes, not just numbers. explain_change splits a rise or fall by page, query, country, device and search appearance, separates lost impressions from a lower click-through rate, and lines the change up with Google's published updates.
• Full indexing audits. Google's API does not expose the Page indexing report's URL lists, so audit_indexing rebuilds them: it inspects every sitemap URL within the daily quota, carries on where it stopped the next day, and can check each live page against what Google last saw.
• Everything the API can do, with guard rails. Reads and writes are both on: it can add and remove properties and submit and remove sitemaps. Changes need the property's exact name, and the tools that make them are marked as writes (deletes as destructive), which clients can use to ask before running them. Turn writes off with GSC_ENABLE_WRITES=0.
• Structured output. Every tool declares an output schema, rows come back as named fields, and every analytics result includes the exact request sent to Google.
• Full API coverage: search analytics (all search types, filters, data states, pagination), hourly data, search appearances, URL inspection (single and concurrent batch), sitemaps and properties, plus a dedicated tool for each search surface (Discover, Images, video, Google News, the News tab) that only accepts what that surface supports.
• Built on the current stack: MCP Python SDK 2.x (protocol 2026-07-28 and older clients alike) and an async client, so batch inspection runs concurrently.

Quick start

You need uv and a Google account with access to at least one Search Console property.

1. Create an OAuth client in Google Cloud (about five minutes, once):

   1. Open console.cloud.google.com and create or pick a project.
   2. APIs & Services > Library: enable the Google Search Console API.
   3. Google Auth Platform > Branding: fill in an app name and your email.
   4. Google Auth Platform > Audience: choose External, add your Google account as a test user, then click Publish app so the status is In production. Skip this and Google expires your login every 7 days.
   5. Google Auth Platform > Clients > Create client: type Desktop app. Download the JSON and keep it outside any repository, for example ~/.config/open-gsc-mcp/client_secret.json.

2. Sign in (opens a browser once; the server itself never does):

   sh

   uvx open-gsc-mcp@latest auth login --client-file ~/.config/open-gsc-mcp/client_secret.json

   Google shows "Google hasn't verified this app" because the app is yours and unreviewed; choose Advanced > Go to (your app). When it finishes, the command lists the properties it can see.

3. Add the server to your client (below), restart the client, and ask something like "Which queries lost the most clicks this month on example.com?"

Client configuration

Claude Code

claude mcp add --scope user gsc -- uvx open-gsc-mcp@latest

Claude Desktop: edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{  "mcpServers": {    "gsc": {      "command": "uvx",      "args": ["open-gsc-mcp@latest"]    }  }}

If Claude Desktop reports that uvx cannot be found, use its absolute path (which uvx on macOS and Linux, where uvx on Windows).

Cursor: add the same mcpServers block to ~/.cursor/mcp.json.

@latest makes uvx check for a new release each time the client starts the server. Without it, uvx keeps running the version it cached the first time. To upgrade only when you choose, pin a version instead, such as [email protected].

To pass settings, add an env object to the server entry, or -e NAME=value to claude mcp add. Paths must be absolute: clients start the server from an arbitrary working directory.

Service account (headless)

For servers, CI or shared machines, use a service account instead of a personal login:

1. In Google Cloud, IAM & Admin > Service Accounts: create one, then Keys > Add key > JSON. (Some organizations block key creation by policy.)

2. In Search Console, Settings > Users and permissions > Add user: add the service account's email to each property, with Full or Restricted permission.

3. Point the server at the key:

   sh

   claude mcp add --scope user gsc -e GSC_SERVICE_ACCOUNT_FILE=/abs/path/key.json -- uvx open-gsc-mcp@latest

When GSC_SERVICE_ACCOUNT_FILE is set it takes precedence over any OAuth login.

Tools

query_news_analytics from 1.1.0 is deprecated: calls still work and go to the new news tool its source selects, until it is removed in 2.0.0.

Four tools make changes: submit_sitemap, delete_sitemap, add_site and delete_site. They accept only a property's exact site_url, and a sitemap must belong to that property. They are annotated as writes (deletes as destructive) and tell the model to confirm with you first, but the server does not ask you itself: whether you see a prompt depends on your client's permission settings. These four are every change Google's API allows: it cannot request indexing, remove URLs from search, or manage users and settings. Set GSC_ENABLE_WRITES=0 for a server without them.

Sites can be given as sc-domain:example.com, https://www.example.com/, a bare example.com, or any URL on the site. Anything but the exact property is resolved against your real property list, to the property that contains it; results then say so, and for a page URL they note that they cover the whole property.

Prompts: weekly_report, indexing_audit and content_opportunities are ready-made workflows with concrete dates and exact tool calls.

Indexing audits save their progress locally, so each audit_indexing call carries on where the last one stopped. Inspections take a few seconds each, so a call covers about 50 URLs; for a large site, run uvx open-gsc-mcp@latest audit sc-domain:example.com in a terminal (or daily from cron) to use the full 2,000 a day, then ask your assistant about the results.

Configuration

Command line:

uvx open-gsc-mcp@latest              # run the MCP server over stdio (what clients do)uvx open-gsc-mcp@latest auth login   # sign in; --read-only to grant reads only, --no-browser over SSHuvx open-gsc-mcp@latest auth status  # which credentials are used, and do they workuvx open-gsc-mcp@latest auth logout  # revoke and delete the saved loginuvx open-gsc-mcp@latest audit SITE   # inspect up to a day's 2,000 sitemap URLs; --fetch-pages

API behavior handled for you

Not available through Google's API, so no server can provide them: the generative AI (AI Overviews and AI Mode) report, platform properties (Instagram, TikTok, X, YouTube), the branded query filter, Core Web Vitals, manual actions and links.

Troubleshooting

• "Your Google login has expired or was revoked (invalid_grant)": the OAuth app is probably still in Testing status, which limits logins to 7 days. Publish it (Quick start, step 1.4) and run auth login again.
• "Not signed in": run uvx open-gsc-mcp@latest auth login --client-file ..., or set GSC_SERVICE_ACCOUNT_FILE.
• No properties, or 403 for a service account: add the service account's email as a user on the property in Search Console. Changes also need Owner or Full permission there.
• "Your Google login only allows reading": you signed in before full access was the default, or with --read-only. Run auth login again to allow changes.
• Empty results: check the date range (Pacific Time; final data lags 2-3 days), the search_type, and filters. Each result's notes and request show what was asked.
• Check the setup end to end: uvx open-gsc-mcp@latest auth status.

Security and privacy

• Runs locally over stdio, with no telemetry. It calls Google's API and reads Google's public update feed (status.search.google.com) for explain_change.
• An indexing audit also reads your property's sitemaps and, with fetch_pages, its pages. It fetches only URLs inside the property, never hosts that resolve to private or local addresses, and follows redirects only while they stay inside. From each page it keeps only the status code, redirects, robots directives and canonical URL.
• Audit progress (URLs and their index status) is kept in one SQLite file in your user data directory (GSC_DATA_DIR), readable only by you.
• The OAuth login is stored in your user config directory with owner-only permissions. auth logout revokes it at Google and deletes it.
• Logins ask Google for full Search Console access, which the write tools need. Use auth login --read-only (or GSC_ENABLE_WRITES=0) to grant read access only.
• Query and page strings come from searchers and other websites. The server tells the model to treat them as data, not instructions.

Report vulnerabilities privately; see SECURITY.md.

Development

git clone https://github.com/onlymoein/google-search-console-mcpcd google-search-console-mcpuv syncuv run pytest                # unit and in-memory MCP tests, no networkuv run ruff check . && uv run ruff format --check . && uv run pyright

Live, read-only checks against your own property:

export GSC_SERVICE_ACCOUNT_FILE=/abs/path/key.jsonGSC_TEST_SITE=sc-domain:example.com uv run pytest -m liveuv run python scripts/probe_compat.py sc-domain:example.com

See CONTRIBUTING.md for the project layout and how to add a tool.

License

MIT