MCP Gsc README

Google Search Console MCP Server for SEOs

A Model Context Protocol (MCP) server that connects Google Search Console (GSC) to AI assistants, allowing you to analyze your SEO data through natural language conversations. Works with Claude Desktop, Cursor, Codex CLI, Gemini CLI, Antigravity, and any other MCP-compatible client.

Skip setup, get more. A more advanced hosted version — one-click sign-in, GA4, Google Ads, SERP lookups, keyword research, and a lot more. Works with Claude, ChatGPT, Cursor, Grok, and any other MCP client. → Advanced MCP for SEO professionals (hosted)

What's New

[0.4.2] — November 2026

• Read-only OAuth tokens work again, and a failed refresh no longer deletes your token — the server now requests only the scope it needs (read-only by default, write only when GSC_ALLOW_DESTRUCTIVE=true) and loads existing tokens with their granted scope, so a webmasters.readonly token refreshes instead of being rejected. A transient refresh failure keeps your token file instead of silently deleting it. Thanks @christian-fastcorp. (#56)
• Tools no longer block the event loop — blocking Search Console API calls now run in a worker thread, so a slow request no longer stalls every other in-flight tool call. Thanks @kuldiph. (#52)
• get_advanced_search_analytics pagination fixed when capped — requesting more than 25,000 rows no longer drops the next page; has_more/next_start_row use the effective (capped) limit. Thanks @dajiaohuang. (#62)
• Optional tool arguments accept an explicit null — nine str | None parameters now validate when a client sends the advertised null default. Thanks @vishalhabib99. (#58)
• Raised the mcp[cli] floor to >=1.27.2 (kept the <2.0.0 cap) to clear four published SDK advisories. Thanks @prateekparshwa. (#40)

See the full version history in the Changelog below.

What Can This Do?

Property Management

• See all your GSC properties in one place
• Get verification details and ownership information
• Add or remove properties from your account

Search Analytics & Reporting

• Discover which queries bring visitors to your site
• Track impressions, clicks, and click-through rates
• Analyze performance trends and compare time periods
• Visualize data with charts created by your AI assistant

URL Inspection & Indexing

• Check if specific pages have indexing problems
• See when Google last crawled your pages
• Inspect multiple URLs at once to identify patterns

Sitemap Management

• View all sitemaps and their status
• Submit new sitemaps
• Check for errors or warnings

Available Tools

Ask your AI assistant to "call get_capabilities" for the full list of all 20 tools.

Getting Started

Step 1 — Set Up Google API Credentials

You need credentials before configuring any client. Pick one method:

Option A — OAuth (Recommended — uses your own Google account)

1. Go to Google Cloud Console and create or select a project
2. Enable the Search Console API
3. Go to Credentials → Create Credentials → OAuth client ID
4. Configure the OAuth consent screen, select Desktop app, click Create
5. Download the JSON file — save it somewhere permanent (e.g. ~/Documents/client_secrets.json)

On first use, a browser window will open asking you to sign in to your Google account. After that, the token is saved and no browser interaction is needed again.

Option B — Service Account (For automation or team use)

1. Go to Google Cloud Console and create or select a project
2. Enable the Search Console API
3. Go to Credentials → Create Credentials → Service Account
4. Go to the Keys tab → Add Key → Create new key → JSON → Download
5. Save the file somewhere permanent (e.g. ~/Documents/service_account.json)
6. Add the service account email to your GSC property: Search Console → Settings → Users and permissions → Add user → Full access

🎥 Watch the step-by-step setup tutorial for this section

Updated 2026 — covers the full installation process using the new uvx method, from setting up your Google credentials to your first successful query.

Step 2 — Installation

Option A — uvx (Recommended)

No cloning, no Python installation, no virtual environments. uvx downloads and runs the server automatically and keeps it up to date.

Install uv — open Terminal and run all three commands in order:

# 1. Download and install
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Activate in the current Terminal session
source $HOME/.local/bin/env

# 3. Make it permanent for all future sessions
echo 'source $HOME/.local/bin/env' >> ~/.zshrc

Verify:

uv --version

Why all three commands? The installer puts uv in ~/.local/bin, but your already-open Terminal session doesn't know about that folder yet. Step 2 activates it immediately. Step 3 ensures every future Terminal window has it automatically.

Now configure your AI client:

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json

OAuth:

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
      }
    }
  }
}

Service Account:

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

Cursor

Config file: ~/.cursor/mcp.json

OAuth:

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
      }
    }
  }
}

Codex CLI

Config file: ~/.codex/config.toml

OAuth:

[mcp_servers.gscServer]
command = "/FULL/PATH/TO/uvx"
args = ["mcp-search-console"]
enabled = true
env = { GSC_OAUTH_CLIENT_SECRETS_FILE = "/full/path/to/client_secrets.json" }

Service Account:

[mcp_servers.gscServer]
command = "/FULL/PATH/TO/uvx"
args = ["mcp-search-console"]
enabled = true
env = { GSC_CREDENTIALS_PATH = "/full/path/to/service_account.json", GSC_SKIP_OAUTH = "true" }

Finding your uvx path: On macOS/Linux run which uvx in Terminal after installing uv (typically /Users/YOUR_NAME/.local/bin/uvx). On Windows, run Get-Command uvx | Select-Object -ExpandProperty Source in PowerShell (or where uvx in cmd) — it's usually C:\Users\YOUR_NAME\.local\bin\uvx.exe. Replace /FULL/PATH/TO/uvx in the configs above with that path.

Why the full path? GUI apps like Claude Desktop and Cursor launch without reading your shell config (~/.zshrc), so they don't know about ~/.local/bin. Using the full path guarantees it works regardless of how the app is launched. If you see a spawn uvx ENOENT error, this is the fix.

After saving the config, fully quit the app (Cmd+Q) and reopen it.

For OAuth: on first use, a browser window will open automatically for login. After that, the token is cached and you won't be asked again.

Option B — Clone (Advanced)

Prefer a video walkthrough for this method? The tutorial below covers the clone install path step by step — virtual environment setup, dependencies, and config:

Use this if you want to modify the code or run a specific local version. This method uses the video tutorial above for the credential setup steps.

Requires Python 3.11+. This server will not start on Python 3.10 or older — and when it's launched by a GUI client like Claude Desktop, it fails silently (no tools appear and no log file is written). Check your version with python --version. If it's below 3.11, install Python 3.11 or newer and recreate your virtual environment. The uvx method (Option A) avoids this entirely by managing the Python version for you, so it's the recommended path on Windows.

Clone the repo:

git clone https://github.com/AminForou/mcp-gsc.git
cd mcp-gsc

Or download the ZIP from the green Code button at the top of this page and unzip it.

Set up the environment:

uv venv .venv
uv pip install -r requirements.txt

Configure your AI client (Claude Desktop example):

OAuth:

{
  "mcpServers": {
    "gscServer": {
      "command": "/full/path/to/mcp-gsc/.venv/bin/python",
      "args": ["/full/path/to/mcp-gsc/gsc_server.py"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
      }
    }
  }
}

Service Account:

{
  "mcpServers": {
    "gscServer": {
      "command": "/full/path/to/mcp-gsc/.venv/bin/python",
      "args": ["/full/path/to/mcp-gsc/gsc_server.py"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

Mac path examples:

• Python: /Users/yourname/Documents/mcp-gsc/.venv/bin/python
• Script: /Users/yourname/Documents/mcp-gsc/gsc_server.py

Step 3 — Test

Ask your AI assistant: "List my GSC properties"

If you see your properties — it's working. If not, ask: "Call get_capabilities" to see auth status and diagnose the issue.

Environment Variables Reference

Cursor Marketplace

One-click install available — search for mcp-search-console in the Cursor Marketplace.

After installing, configure your credentials (see Step 1 above) then use the bundled skills directly in Cursor Agent chat:

Sample Prompts

Troubleshooting

spawn uvx ENOENT or command not found: uvx

Your AI client can't find uvx. Use the full path instead of just uvx:

# Find your full path (macOS/Linux):
which uvx
# Typically: /Users/YOUR_NAME/.local/bin/uvx

# Find your full path (Windows PowerShell):
Get-Command uvx | Select-Object -ExpandProperty Source
# Typically: C:\Users\YOUR_NAME\.local\bin\uvx.exe

Replace "command": "uvx" with the full path (e.g. "command": "/Users/YOUR_NAME/.local/bin/uvx") in your config.

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

The installer updates ~/.local/bin but your current Terminal session doesn't see it yet. Run:

source $HOME/.local/bin/env

Then add it permanently:

echo 'source $HOME/.local/bin/env' >> ~/.zshrc

Authentication failed / credentials file not found

Make sure you are using the absolute path to your credentials file — not a relative path, not ~/. Example:

/Users/yourname/Documents/client_secrets.json   ✅
~/Documents/client_secrets.json                 ✅
client_secrets.json                              ❌

MCP only works in Claude Desktop app, not the website

The MCP server runs locally on your machine. It only works in the Claude Desktop app (downloaded from claude.ai/download), not in the claude.ai browser interface.

AI Client Configuration Issues

1. Make sure all file paths in your config are correct absolute paths
2. Fully quit (Cmd+Q) and reopen the app after any config change — just closing the window is not enough
3. Ask your AI assistant to "call get_capabilities" — it will report the exact auth status and error

Safety: Destructive Operations

By default, add_site, delete_site, and delete_sitemap are disabled. To enable them:

"GSC_ALLOW_DESTRUCTIVE": "true"

Remote Deployment & Docker (Advanced)

The standard setup runs the server locally. This section is only for users who want to run it on a remote server or in a container.

HTTP Transport

MCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=3001 python gsc_server.py

Docker

docker build -t mcp-gsc .

docker run \
  -e MCP_TRANSPORT=sse \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=3001 \
  -e GSC_CREDENTIALS_PATH=/app/credentials.json \
  -v /path/to/credentials.json:/app/credentials.json \
  -p 3001:3001 \
  mcp-gsc

Related Tools

Advanced GSC Visualizer — A Chrome extension (14,000+ users) with interactive charts, one-click export of up to 25,000 rows, keyword cannibalization detection, and an AI assistant — all directly inside Google Search Console. Built by the same author. Install from the Chrome Web Store →

Contributing

Found a bug or have an idea for improvement? Open an issue or submit a pull request on GitHub.

Thanks to everyone who has reported issues and contributed fixes, including @patrickweh, @remotesensei, @JKdreaming, and @kuldiph.

License

MIT License. See the LICENSE file for details.

Changelog

[0.4.2] — November 2026

• Fixed OAuth for read-only tokens: the server now requests only the scope the enabled tools need (webmasters.readonly by default, the write scope only when GSC_ALLOW_DESTRUCTIVE=true) and loads an existing token with its granted scope, so a webmasters.readonly token refreshes instead of failing with invalid_scope. A failed refresh (or an unreadable token file) no longer deletes the token file — a transient error must not destroy a working credential. (Fixes #56; thanks @christian-fastcorp)
• Blocking google-api-python-client calls now run off the event loop via a worker thread (_execute), so a slow request no longer stalls other concurrent tool calls. (Fixes #52; thanks @kuldiph)
• Fixed get_advanced_search_analytics pagination when row_limit exceeds the API cap of 25,000: has_more and next_start_row now use the effective capped limit instead of the requested one, so the next page is no longer dropped. (Fixes #62; thanks @dajiaohuang)
• Optional tool arguments annotated str | None = None now accept an explicit null from clients that send the advertised default, instead of failing argument validation. (Fixes #58; thanks @vishalhabib99)
• Raised the mcp[cli] dependency floor to >=1.27.2 (keeping the <2.0.0 cap from 0.3.3) to clear four published MCP SDK advisories. (Fixes #40; thanks @prateekparshwa)

[0.4.1] — September 2026

• check_indexing_issues now inspects URLs concurrently (same fix as #31), avoiding timeouts on full 10-URL batches against sc-domain:* properties. (Fixes #55; thanks @kuldiph)
• Removed a leftover orderBy from get_search_by_page_query — a dead field the Search Analytics API ignores, matching the #54 cleanup. (Fixes #55; thanks @kuldiph)

[0.4.0] — September 2026

• Fixed rich-result issue reporting in inspect_url_enhanced and batch_url_inspection — issues are read from detectedItems[].items[].issues[] (issueMessage), the key the API actually returns, so problems are no longer silently dropped. (Fixes #46, #48; thanks @patrickweh)
• batch_url_inspection now inspects URLs concurrently, so full 10-URL batches complete within the client timeout even on slower sc-domain:* properties. (Fixes #31; thanks @remotesensei)
• compare_search_periods now computes deltas as Period 1 relative to Period 2 (Period 2 as the percentage baseline, positive = Period 1 better), with the direction documented. (Fixes #42; thanks @JKdreaming)
• get_advanced_search_analytics applies sort_by/sort_direction client-side instead of sending an orderBy the Search Analytics API ignores. (Fixes #54; thanks @kuldiph)
• Replaced three bare except: clauses with except Exception: so KeyboardInterrupt/SystemExit are no longer swallowed. (Fixes #53; thanks @kuldiph)
• Breaking: batch_url_inspection renames the per-URL verdict field to index_verdict.

[0.3.3] — July 2026

• Pinned mcp[cli]>=1.3.0,<2.0.0. The mcp SDK 2.0.0 removed mcp.server.fastmcp, breaking all fresh uvx installs with ModuleNotFoundError. Capping below 2.0 restores working installs. (Fixes #41)

[0.3.2] — April 2026

• OAuth browser flow fixed for uvx — removed isatty block that prevented the OAuth browser window from opening when running as an MCP subprocess on macOS. OAuth + uvx now works out of the box.
• get_capabilities tool — returns all available tools grouped by category plus live auth status in one call.
• Better auth error messages — all tools now explicitly tell you to call reauthenticate when credentials are missing or expired.
• Improved list_properties description — better semantic tool discovery in clients that use lazy tool loading.

[0.3.1] — April 2026

• Fixed list_properties masking real auth errors; fail-fast on missing credentials.

[0.3.0] — April 2026

• Cursor Marketplace plugin with 4 bundled SEO skills
• Stable token storage in platform user config dir (survives uvx upgrades)
• Structured JSON output for all data tools
• 39 unit tests

[0.2.2] — April 2026

• Safety mode for destructive tools (disabled by default)
• HTTP/SSE transport for remote deployments
• Dockerfile

[0.2.1] — March 2026

• reauthenticate tool for switching Google accounts
• Fixed sitemap TypeError crash
• Fixed domain property 404 errors

[0.2.0] — March 2026

• dataState: "all" by default (matches GSC dashboard)
• Flexible row_limit parameter (up to 500)
• Multi-dimension filtering for advanced analytics

[0.1.0] — Initial release

• 19 tools covering property management, search analytics, URL inspection, and sitemap management
• OAuth and service account authentication