Google Search Console MCP Server for SEOs — Sam GSC MCP

Sam GSC MCP connects Google Search Console to your AI assistant so you can analyse SEO data in plain English — "which pages lost clicks this month?", "find keyword cannibalization", "is this URL indexed?". It works with Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Codex CLI, Gemini CLI and any other MCP client.

It is an all-in-one server: search analytics, SEO insight tools, URL inspection, sitemaps, hourly data, CSV export, the Indexing API and 11 ready-made SEO skills — in one place.

Contents

• What's New

• Features

• Prerequisites

• Setup Instructions — Step 1 · Step 2 · Step 3 · Step 4 · Service account · Step 5 · Step 6 · Step 7

• Available Tools

• SEO Skills & Prompts

• Environment Variables Reference

• Sample Prompts

• Safety & Privacy

• Remote Deployment & Docker

• Troubleshooting

• Process Screenshots

• Contributing · Credits · License · Changelog

Related MCP server: GSC MCP Server

What's New

• One server, everything included — 40 tools for analytics, insights, inspection, indexing and sitemaps.

• SEO insight tools — find_striking_distance_keywords, find_keyword_cannibalization, get_brand_vs_nonbrand and find_low_ctr_opportunities return ranked, ready-to-act lists instead of raw rows.

• Hourly data — get_hourly_performance uses Google's hourly Search Analytics data (last ~10 days).

• CSV export — export_search_analytics pulls up to 500,000 rows (auto-paginated) into a CSV on your computer.

• Real Indexing API — request_indexing / get_indexing_status (opt-in).

• Coverage & mobile reports from live URL Inspection — sampled from your top pages, your sitemap or a URL list.

• No more exact-site_url headaches — example.com is matched to sc-domain:example.com or https://www.example.com/ automatically, and GSC_SITE_URL makes site_url optional.

• Fix setup without restarting — setup_gsc_access applies new credential paths in-chat (with interactive prompts on clients that support them).

• Choose your tools — GSC_TOOLSETS, GSC_DISABLED_TOOLS and GSC_READ_ONLY for clients with tool limits or cautious teams.

• 11 SEO skills + 6 one-click prompts, a Claude Code plugin, and example configs for every major client.

• Future-proof — runs on MCP Python SDK 1.x and 2.x.

Full history: CHANGELOG.md.

Features

Property management

• List every Search Console property you can access, with permission levels

• Verification and ownership details

• Add or remove properties (guarded by a safety flag)

Search analytics & reporting

• Clicks, impressions, CTR and position by query, page, country, device, date, search appearance or hour

• Up to 25,000 rows per call with pagination, sorting, regex filters and multi-filter AND logic

• Web, Image, Video, News, Discover and Google News search types

• Performance overview with daily trend, best/worst day

• This period vs previous period summary with % changes

• Item-by-item period comparison (gainers, losers, new and lost queries/pages)

• Queries for a single page

• Hourly performance (last ~10 days)

• Bulk CSV export

SEO insights (computed for you)

• Striking-distance keywords (positions 4–20) ranked by estimated click gain

• Keyword cannibalization with a suggested primary page per query

• Branded vs non-branded traffic share

• Low-CTR / "silent reference" pages (likely answered by AI Overviews or snippets)

URL inspection & indexing

• Full inspection: index verdict, coverage state, last crawl, Google vs declared canonical, robots, fetch state, rich results (with issues), mobile usability and AMP

• Quick "is it indexed?" check

• Batch inspection and grouped indexing-issue report (concurrent, quota-aware)

• Coverage report and mobile signals sampled from top pages, a sitemap or your list

• Optional Indexing API notifications (URL_UPDATED / URL_DELETED)

Sitemaps

• List (including children of a sitemap index), details, submit/resubmit, delete (guarded)

Built for AI assistants

• 11 SEO playbooks (skills) and 6 workflow prompts, also exposed as MCP resources

• Schema discovery tools so the AI never guesses dimension or operator names

• Friendly JSON errors that say exactly how to fix the problem

• Tool annotations (read-only / destructive hints) for safer client approvals

Auth & operations

• OAuth (your Google account), service account, or Application Default Credentials

• Read-only mode, destructive-operation flag, tool-group filtering

• stdio (default), SSE and streamable HTTP transports; Docker image

• Works with MCP SDK 1.x and 2.x; Python 3.10–3.13; no telemetry

Prerequisites

Install uv (it downloads the right Python for you):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env            # use it in the current terminal

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then find the full path to uvx — you'll paste it into your AI client config:

which uvx          # macOS/Linux → e.g. /Users/you/.local/bin/uvx
where uvx          # Windows     → e.g. C:\Users\you\.local\bin\uvx.exe

Note: local MCP servers run on your computer, so use the desktop/CLI apps. The claude.ai website cannot start a local server (see Remote deployment if you need that).

Setup Instructions

Choose how the server signs in to Google:

Step 1 — Create a Google Cloud project

1. Go to console.cloud.google.com and open the project picker at the top.

2. Click New project, name it (for example sam-gsc-mcp) and click Create.

3. Make sure the new project is selected in the picker.

Step 2 — Enable the Search Console API

1. Open Google Search Console API in the API Library.

2. Click Enable.

3. (Optional) Only if you will use request_indexing: also enable the Web Search Indexing API.

Step 3 — Configure the OAuth consent screen

1. Open Google Auth Platform and click Get started.

2. Branding: app name Sam GSC MCP, your email as support and developer contact.

3. Audience: choose External.

4. Test users: add the Gmail/Workspace address that has access to your Search Console properties.

5. Recommended: click Publish app. In Testing mode Google expires refresh tokens after 7 days, which means signing in again every week. Publishing your own app is fine — you will just see an "unverified app" notice once.

Step 4 — Create the OAuth client (Desktop app)

1. In Google Auth Platform go to Clients → Create client.

2. Application type: Desktop app (not "Web application"). Name it anything.

3. Click Create, then Download JSON.

4. Save the file somewhere permanent, e.g. ~/secure/client_secrets.json, and note its absolute path.

Keep this file private. Never commit it — this repo's .gitignore already blocks common credential file names.

Alternative — Service account

1. Go to IAM & Admin → Service accounts → Create service account (no project roles are needed).

2. Open it → Keys → Add key → Create new key → JSON → Create. The key downloads; store it safely.

3. Copy the client_email (e.g. gsc-bot@your-project.iam.gserviceaccount.com).

4. In Search Console, for each property: Settings → Users and permissions → Add user, paste the email, permission Full (use Owner only if you will use the Indexing API).

Step 5 — Install and connect your AI client

Nothing to clone — uvx downloads and runs the server straight from GitHub. Replace /FULL/PATH/TO/... with your paths.

Claude Desktop

Open Settings → Developer → Edit Config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json).

OAuth:

{
  "mcpServers": {
    "sam-gsc": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["--from", "git+https://github.com/krishanthsam/sam-gsc-mcp", "sam-gsc-mcp"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/FULL/PATH/TO/client_secrets.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

Service account:

{
  "mcpServers": {
    "sam-gsc": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["--from", "git+https://github.com/krishanthsam/sam-gsc-mcp", "sam-gsc-mcp"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/FULL/PATH/TO/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

GSC_SITE_URL is optional — it sets a default property so you don't have to name it every time. Save, then fully quit Claude Desktop (Cmd+Q on macOS, or right-click the tray icon → Quit on Windows) and reopen it.

Claude Code

claude mcp add sam-gsc --scope user \
  -e GSC_OAUTH_CLIENT_SECRETS_FILE=/FULL/PATH/TO/client_secrets.json \
  -- uvx --from git+https://github.com/krishanthsam/sam-gsc-mcp sam-gsc-mcp

Or install it as a plugin (server + all 11 skills):

/plugin marketplace add krishanthsam/sam-gsc-mcp
/plugin install sam-gsc-mcp@sam-gsc-mcp

The plugin reads GSC_OAUTH_CLIENT_SECRETS_FILE, GSC_CREDENTIALS_PATH and GSC_SITE_URL from your shell environment.

Cursor

~/.cursor/mcp.json (or Settings → MCP → Add new server) — same JSON as Claude Desktop. Cursor limits the total number of tools, so you can load only some groups:

"env": {
  "GSC_OAUTH_CLIENT_SECRETS_FILE": "/FULL/PATH/TO/client_secrets.json",
  "GSC_TOOLSETS": "setup,properties,analytics,insights,inspection,sitemaps"
}

VS Code (GitHub Copilot agent mode)

.vscode/mcp.json in your workspace, or MCP: Add Server from the command palette:

{
  "servers": {
    "sam-gsc": {
      "type": "stdio",
      "command": "/FULL/PATH/TO/uvx",
      "args": ["--from", "git+https://github.com/krishanthsam/sam-gsc-mcp", "sam-gsc-mcp"],
      "env": { "GSC_OAUTH_CLIENT_SECRETS_FILE": "/FULL/PATH/TO/client_secrets.json" }
    }
  }
}

Windsurf, Gemini CLI, Codex CLI and others

All examples live in examples/.

Option B — Clone (to modify the code)

git clone https://github.com/krishanthsam/sam-gsc-mcp.git
cd sam-gsc-mcp
uv venv && uv pip install -e ".[dev]"      # or: python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"

Then point your client at the virtual-env Python:

"command": "/FULL/PATH/TO/sam-gsc-mcp/.venv/bin/python",
"args": ["-m", "sam_gsc_mcp"]

(Windows: C:\\path\\to\\sam-gsc-mcp\\.venv\\Scripts\\python.exe.) Run the tests with pytest.

Step 6 — Sign in with Google (OAuth only)

The first time a tool needs data (or when you ask the AI to run reauthenticate), a browser tab opens:

1. Pick the Google account that can see your Search Console properties.

2. If you see "Google hasn't verified this app", click Advanced → Go to Sam GSC MCP — it's your own OAuth client.

3. Allow "View and manage Search Console data".

4. When the tab says "Sam GSC MCP is connected", close it. The token is saved in your OS config folder and refreshed automatically — you won't be asked again.

Step 7 — Test it

Ask your assistant:

List my GSC properties.

You should see your properties. If not, ask "call get_capabilities" — it reports the auth status, the settings in use and which tools are enabled.

Available Tools

40 tools (38 enabled by default) in 9 groups. site_url is optional everywhere when GSC_SITE_URL is set, and accepts example.com, https://www.example.com/ or sc-domain:example.com.

Setup & server

Reference (schema)

SEO skills (playbooks)

Properties

Search analytics & reporting

SEO insights

URL inspection & indexing status

Indexing API (opt-in: GSC_ENABLE_INDEXING_API=true)

Google officially supports the Indexing API only for pages with JobPosting or BroadcastEvent markup, the account must be an Owner of the property, and the default quota is 200 notifications per day. For other pages use Request indexing in Search Console's URL Inspection.

Sitemaps

🔒 = disabled until GSC_ALLOW_DESTRUCTIVE=true.

Compatibility aliases (GSC_COMPAT_ALIASES=true): list_sites, list_gsc_sites, get_performance_data, get_url_inspection_result, get_sitemap_data, submit_url — common alternative tool names, so older prompts keep working.

Output conventions: every tool returns compact JSON. ctr is a percentage (3.25 = 3.25 %), position is an average where lower is better, and errors come back as {"error": "...", "how_to_fix": [...]}.

SEO Skills & Prompts

Skills are step-by-step playbooks the AI can read with skill_read (also available as MCP resources skill://<id> and, in Claude Code, as plugin skills). Prompts appear in your client's prompt or slash-command menu.

Prompts: seo-weekly-report, content-opportunities, cannibalization-check, indexing-audit, analyze-brand-visibility, diagnose-traffic-drop.

Environment Variables Reference

All paths must be absolute (~ and $HOME are expanded). A full commented template is in .env.example.

Authentication

Behaviour

Files

Transport (remote use)

Settings saved by setup_gsc_access go to <config dir>/config.json; environment variables always win over it.

Sample Prompts

Multi-step requests that work well

• "Run the SEO weekly report for example.com and turn it into a client-ready summary."

• "Find content decay: pages that lost the most clicks over the last 3 months, and what queries they lost."

• "Audit indexing for my top 20 pages and prioritise the fixes."

• "Split my queries by intent and tell me which service pages I'm missing."

Safety & Privacy

• Runs locally. Credentials stay on your machine; the server only talks to Google's APIs (and, if you ask, GitHub for check_for_updates and your own sitemap URL for coverage reports). No telemetry.

• Destructive operations are off by default (GSC_ALLOW_DESTRUCTIVE). Tool annotations mark them so clients can ask for confirmation.

• Read-only mode (GSC_READ_ONLY=true) requests the webmasters.readonly scope and hides every write tool.

• setup_gsc_access stores only file paths in config.json, never key contents. The OAuth token is saved with user-only file permissions.

• Never commit client_secrets.json, service account keys or token.json — .gitignore blocks the common names.

Remote Deployment & Docker (Advanced)

Only needed if you want to run the server on another machine. For desktop use, stdio is simpler and safer.

MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=3001 \
GSC_CREDENTIALS_PATH=/secrets/service_account.json GSC_SKIP_OAUTH=true \
uvx --from git+https://github.com/krishanthsam/sam-gsc-mcp sam-gsc-mcp
# clients connect to http://HOST:3001/mcp   (SSE: MCP_TRANSPORT=sse → http://HOST:3001/sse)

Docker (service account recommended — there is no browser inside a container):

docker build -t sam-gsc-mcp .
docker run -p 3001:3001 \
  -e GSC_CREDENTIALS_PATH=/secrets/service_account.json -e GSC_SKIP_OAUTH=true -e GSC_READ_ONLY=true \
  -v /path/to/service_account.json:/secrets/service_account.json:ro \
  -v sam-gsc-data:/data \
  sam-gsc-mcp

Or use examples/docker-compose.yml.

⚠️ The HTTP transport has no built-in authentication. Keep it on localhost, a private network/VPN, or behind a reverse proxy that adds auth and HTTPS. Anyone who can reach the port can read your Search Console data.

OAuth on a remote machine: set GSC_OAUTH_PORT=8765, forward it (ssh -L 8765:localhost:8765 server), then open the sign-in URL printed in the server log.

Troubleshooting

spawn uvx ENOENT / command not found: uvx

Your AI client can't find uvx. Use the full path from which uvx (macOS/Linux) or where uvx (Windows) as "command". GUI apps don't read your shell profile, so plain uvx often fails.

uv --version says "command not found" right after installing

Run source $HOME/.local/bin/env, then add it to your shell profile: echo 'source $HOME/.local/bin/env' >> ~/.zshrc.

No tools appear in the client

1. Fully quit and reopen the app after editing the config (closing the window isn't enough).

2. Check the JSON is valid (no trailing commas).

3. Look at the MCP log: Claude Desktop → Settings → Developer → Open Logs Folder (mcp-server-sam-gsc.log).

4. The first uvx run downloads packages and can take a minute; if the client times out, run uvx --from git+https://github.com/krishanthsam/sam-gsc-mcp sam-gsc-mcp once in a terminal (stop it with Ctrl+C), then restart the client.

"Not authenticated" / credentials file not found

• Use absolute paths: /Users/you/secure/client_secrets.json ✅ · client_secrets.json ❌

• With uvx the server runs from a cache folder, so files "next to the server" are never found — always set the env var.

• Ask the AI to call get_capabilities (shows exactly what's wrong) or setup_gsc_access with the path.

Error 403: access_denied during Google sign-in

Your account isn't a test user of the OAuth app. Add it under Google Auth Platform → Audience → Test users, or publish the app (Step 3).

Signed in, but I have to log in again every week

The OAuth app is in Testing mode, where Google expires refresh tokens after 7 days. Publish it (Step 3).

Property ... was not found (404) or Permission denied (403)

• Run list_properties and use the exact string. Domain properties look like sc-domain:example.com; URL-prefix properties need protocol, www and trailing slash (https://www.example.com/). Sam GSC MCP auto-matches most variants.

• Service account: add its email in Search Console → Settings → Users and permissions for that property.

• Indexing API errors need Owner permission and the Web Search Indexing API enabled.

"Google Search Console API has not been used in project … or it is disabled"

Enable the API (Step 2) in the same Google Cloud project that issued your credentials, wait a minute and retry.

"No data" for recent days, or numbers differ from the dashboard

Search Console data lags 1–3 days. With GSC_DATA_STATE=final it lags 2–3 days more. Query-level reports exclude anonymised queries, so query totals are lower than site totals — that's normal.

Discover or Google News returns an error

Those search types don't support the query dimension or position. Use page, date, country or device.

Too many URLs

Inspection tools take 10 URLs per call by default. Split the list or raise GSC_MAX_BATCH_URLS (max 100). Quota is 2,000 inspections/day and 600/minute per property.

Timeouts on big inspections or exports

Inspections already run in parallel; reduce the batch size, or raise your client's tool timeout (e.g. Codex tool_timeout_sec, Gemini CLI timeout).

It works in Claude Desktop but not on claude.ai

The website can't start local programs. Use the desktop app, Claude Code or another local client, or host the server remotely (see above).

Python version errors (clone install)

Use Python 3.10 or newer (python3 --version), or use the uvx method, which manages Python for you.

Switch Google account

Ask the AI to run reauthenticate.

Process Screenshots

The images in this guide are simplified illustrations of each screen (labels match the real Google Cloud and Search Console UI), generated by docs/screenshots/make_illustrations.py so they stay readable and up to date. The tools list image is produced from the server's real tool registry.

Prefer real screenshots? Save PNGs with the same names in docs/screenshots/ and change the .svg links above to .png.

Contributing

Issues and pull requests are welcome at github.com/krishanthsam/sam-gsc-mcp.

git clone https://github.com/krishanthsam/sam-gsc-mcp.git && cd sam-gsc-mcp
uv venv && uv pip install -e ".[dev]"
pytest                                        # offline tests with a fake Google API
python docs/screenshots/make_illustrations.py # regenerate the guide images

Project layout:

sam_gsc_mcp/      server.py (tools) · auth.py · gsc.py (requests, errors, site matching) · inspection.py
                  config.py · reference.py · skills.py · prompts.py · compat.py (MCP SDK 1.x/2.x)
skills/           11 SEO playbooks (SKILL.md) — bundled into the package
examples/         ready-to-paste client configs
docs/screenshots/ guide illustrations + generator
tests/            pytest suite

Credits

Built by Krishanth Sam — Website · LinkedIn.

Not affiliated with or endorsed by Google. Google Search Console is a trademark of Google LLC.

License

MIT License — see LICENSE.

Changelog

[1.0.0] — 2026-10-24

• First release: 40 tools, 11 SEO skills and 6 prompts in one server.

• New: SEO insight tools (striking distance, cannibalization, brand vs non-brand, low CTR), hourly data, CSV export, real Indexing API, live coverage and mobile reports, property auto-matching, default property, in-chat setup, read-only mode, tool groups, compatibility aliases, ADC auth, 11 skills, 6 prompts, Claude Code plugin.

• Works on MCP SDK 1.x and 2.x, Python 3.10–3.13. No telemetry.

Full details: CHANGELOG.md.