Google Search Console

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, added GA4 tools. Works with Claude Desktop, Claude Code, Claude.ai, Codex, Cursor, and any MCP client. Only**100 seats**. →](https://search.google.com/search-console/about)[**Advanced GSC MCP (hosted)** - **Fixed fresh installs broken by`mcp`2.0**— pinned`mcp](https://www.advancedgsc.com/mcp?utm_source=github&amp;utm_medium=readme&amp;utm_campaign=mcp-gsc&amp;utm_content=hero-callout)[cli]<2.0.0`. The`mcp`SDK 2.0.0 (released 2026-07-28) removed the`mcp.server.fastmcp`module, so every fresh`uvx mcp-search-console`install crashed on startup with`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`. New installs now resolve a working 1.x SDK again — no`--with "mcp<2"`workaround needed. - **OAuth browser flow fixed for uvx**— removed the`isatty`block that prevented the browser login window from opening when running as an MCP subprocess on macOS. OAuth now works out of the box with`uvx`, no manual terminal run needed. - **`get_capabilities`tool added**— call this to get a full list of available tools and current auth status in one shot. Useful when your AI assistant isn't sure what tools are available. - **Better auth error messages**— all tools now tell you exactly what to do when credentials are missing or expired. - See all your GSC properties in one place - Get verification details and ownership information - Add or remove properties from your account - 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 - Check if specific pages have indexing problems - See when Google last crawled your pages - Inspect multiple URLs at once to identify patterns - View all sitemaps and their status - Submit new sitemaps - Check for errors or warnings *Ask your AI assistant to "call get_capabilities" for the full list of all 20 tools.* You need credentials before configuring any client. Pick one method: #### Option A — OAuth (Recommended — uses your own Google account) - Go to[Google Cloud Consoleand create or select a project - ](https://console.cloud.google.com/)[Enable the Search Console API - Go to](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)[Credentials→ Create Credentials →**OAuth client ID** - Configure the OAuth consent screen, select**Desktop app**, click Create - Download the JSON file — save it somewhere permanent (e.g.`~/Documents/client_secrets.json`) #### Option B — Service Account (For automation or team use) - Go to](https://console.cloud.google.com/apis/credentials)[Google Cloud Consoleand create or select a project - ](https://console.cloud.google.com/)[Enable the Search Console API - Go to](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)[Credentials→ Create Credentials →**Service Account** - Go to the Keys tab → Add Key → Create new key → JSON → Download - Save the file somewhere permanent (e.g.`~/Documents/service_account.json`) - 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.* 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` ``` **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. Config file:`~/Library/Application Support/Claude/claude_desktop_config.json` ``` `{ "mcpServers": { "gscServer": { "command": "/FULL/PATH/TO/uvx", "args": ](https://console.cloud.google.com/apis/credentials)["mcp-search-console"], "env": { "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json" } } } }` ``` ``` `{ "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" } } } }` ``` ``` `{ "mcpServers": { "gscServer": { "command": "/FULL/PATH/TO/uvx", "args": ["mcp-search-console"], "env": { "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json" } } } }` ``` ``` `[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" }` ``` ``` `[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. **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 newerand 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. ``` `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. ``` `uv venv .venv uv pip install -r requirements.txt` ``` **Configure your AI client**(Claude Desktop example): ``` `{ "mcpServers": { "gscServer": { "command": "/full/path/to/mcp-gsc/.venv/bin/python", "args": ](https://www.python.org/downloads/)["/full/path/to/mcp-gsc/gsc_server.py"], "env": { "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json" } } } }` ``` ``` `{ "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" } } } }` ``` - Python:`/Users/yourname/Documents/mcp-gsc/.venv/bin/python` - Script:`/Users/yourname/Documents/mcp-gsc/gsc_server.py` 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. 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: ### `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: ``` `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. - Make sure all file paths in your config are correct absolute paths - Fully quit (`Cmd+Q`) and reopen the app after any config change — just closing the window is not enough - Ask your AI assistant to "call get_capabilities" — it will report the exact auth status and error 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. ``` `MCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=3001 python gsc_server.py` ``` ``` `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` ``` **](https://claude.ai/download)[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.](https://www.advancedgsc.com/?utm_source=github&amp;utm_medium=readme&amp;utm_campaign=mcp-gsc&amp;utm_content=related-tools)[Install from the Chrome Web Store → Found a bug or have an idea for improvement? Open an issue or submit a pull request on GitHub. MIT License. See the](https://chromewebstore.google.com/detail/advanced-gsc-visualizer/cdiccpnglfpnclonhpchpaaoigfpieel)[LICENSEfile for details. - Pinned`mcp](https://github.com/AminForou/mcp-gsc/blob/HEAD/LICENSE)[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) - **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. - Fixed`list_properties`masking real auth errors; fail-fast on missing credentials. - 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 - Safety mode for destructive tools (disabled by default) - HTTP/SSE transport for remote deployments - Dockerfile - `reauthenticate`tool for switching Google accounts - Fixed sitemap TypeError crash - Fixed domain property 404 errors - `dataState: "all"`by default (matches GSC dashboard) - Flexible`row_limit`parameter (up to 500) - Multi-dimension filtering for advanced analytics - 19 tools covering property management, search analytics, URL inspection, and sitemap management - OAuth and service account authentication Free MCP that drives an audit of your marketing. Your AI connects, adsOS digs through your ads, email and site, and hands back a growth plan you can run today. Answers questions on AEO, SEO, web development and branding from the published material of GOJI, a Melbourne digital agency, with a goji.agency URL to cite on every result. Technical SEO audits and crawl insights for AI assistants via MCP. MCP server for SEO — run audits and site checks from your AI assistant.