{ "markdown": "# Google Search Console MCP Server for SEOs\n\nA Model Context Protocol (MCP) server that connects [Google Search Console](https://search.google.com/search-console/about) (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.\n\n> **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**.\n> → [**Advanced GSC MCP (hosted)**](https://www.advancedgsc.com/mcp?utm_source=github&utm_medium=readme&utm_campaign=mcp-gsc&utm_content=hero-callout)\n\n---\n\n## What's New\n\n### [0.3.3] — July 2026\n- **Fixed fresh installs broken by `mcp` 2.0** — pinned `mcp[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.\n\n### [0.3.2] — April 2026\n- **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.\n- **`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.\n- **Better auth error messages** — all tools now tell you exactly what to do when credentials are missing or expired.\n\n---\n\n## What Can This Do?\n\n**Property Management**\n- See all your GSC properties in one place\n- Get verification details and ownership information\n- Add or remove properties from your account\n\n**Search Analytics & Reporting**\n- Discover which queries bring visitors to your site\n- Track impressions, clicks, and click-through rates\n- Analyze performance trends and compare time periods\n- Visualize data with charts created by your AI assistant\n\n**URL Inspection & Indexing**\n- Check if specific pages have indexing problems\n- See when Google last crawled your pages\n- Inspect multiple URLs at once to identify patterns\n\n**Sitemap Management**\n- View all sitemaps and their status\n- Submit new sitemaps\n- Check for errors or warnings\n\n---\n\n## Available Tools\n\n| Tool | What It Does | What You Need to Provide |\n|------|-------------|--------------------------|\n| `get_capabilities` | Lists all tools and shows auth status — call this first if unsure | Nothing |\n| `list_properties` | Shows all your GSC properties | Nothing |\n| `get_site_details` | Details about a specific site | Site URL |\n| `get_search_analytics` | Top queries and pages with clicks, impressions, CTR, position | Site URL, time period |\n| `get_performance_overview` | Summary of site performance | Site URL, time period |\n| `compare_search_periods` | Compare performance between two time periods | Site URL, two date ranges |\n| `get_search_by_page_query` | Search terms driving traffic to a specific page | Site URL, page URL |\n| `get_advanced_search_analytics` | Analytics with filters by country, device, query, page | Site URL |\n| `inspect_url_enhanced` | Detailed crawl/index status for a URL | Site URL, page URL |\n| `batch_url_inspection` | Inspect up to 10 URLs at once | Site URL, list of URLs |\n| `check_indexing_issues` | Check multiple URLs for indexing problems | Site URL, list of URLs |\n| `get_sitemaps` | Lists all sitemaps for a site | Site URL |\n| `list_sitemaps_enhanced` | Detailed sitemap info including errors and warnings | Site URL |\n| `manage_sitemaps` | Submit or delete sitemaps | Site URL, action |\n| `reauthenticate` | Re-run the OAuth browser login (switch accounts) | Nothing |\n\n*Ask your AI assistant to \"call get_capabilities\" for the full list of all 20 tools.*\n\n---\n\n
\n \n \"Skip\n \n
\n\n---\n\n## Getting Started\n\n### Step 1 — Set Up Google API Credentials\n\nYou need credentials before configuring any client. Pick one method:\n\n#### Option A — OAuth (Recommended — uses your own Google account)\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create or select a project\n2. [Enable the Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)\n3. Go to [Credentials](https://console.cloud.google.com/apis/credentials) → Create Credentials → **OAuth client ID**\n4. Configure the OAuth consent screen, select **Desktop app**, click Create\n5. Download the JSON file — save it somewhere permanent (e.g. `~/Documents/client_secrets.json`)\n\nOn 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.\n\n#### Option B — Service Account (For automation or team use)\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create or select a project\n2. [Enable the Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)\n3. Go to [Credentials](https://console.cloud.google.com/apis/credentials) → Create Credentials → **Service Account**\n4. Go to the Keys tab → Add Key → Create new key → JSON → Download\n5. Save the file somewhere permanent (e.g. `~/Documents/service_account.json`)\n6. Add the service account email to your GSC property: Search Console → Settings → Users and permissions → Add user → Full access\n\n#### 🎥 Watch the step-by-step setup tutorial for this section\n\n
\n \n \"GSC\n \n
\n\n*Updated 2026 — covers the full installation process using the new uvx method, from setting up your Google credentials to your first successful query.*\n\n---\n\n### Step 2 — Installation\n\n#### Option A — uvx (Recommended)\n\nNo cloning, no Python installation, no virtual environments. `uvx` downloads and runs the server automatically and keeps it up to date.\n\n**Install uv** — open Terminal and run all three commands in order:\n\n```bash\n# 1. Download and install\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# 2. Activate in the current Terminal session\nsource $HOME/.local/bin/env\n\n# 3. Make it permanent for all future sessions\necho 'source $HOME/.local/bin/env' >> ~/.zshrc\n```\n\nVerify:\n```bash\nuv --version\n```\n\n> **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.\n\nNow configure your AI client:\n\n---\n\n**Claude Desktop**\n\nConfig file: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\nOAuth:\n```json\n{\n \"mcpServers\": {\n \"gscServer\": {\n \"command\": \"/FULL/PATH/TO/uvx\",\n \"args\": [\"mcp-search-console\"],\n \"env\": {\n \"GSC_OAUTH_CLIENT_SECRETS_FILE\": \"/full/path/to/client_secrets.json\"\n }\n }\n }\n}\n```\n\nService Account:\n```json\n{\n \"mcpServers\": {\n \"gscServer\": {\n \"command\": \"/FULL/PATH/TO/uvx\",\n \"args\": [\"mcp-search-console\"],\n \"env\": {\n \"GSC_CREDENTIALS_PATH\": \"/full/path/to/service_account.json\",\n \"GSC_SKIP_OAUTH\": \"true\"\n }\n }\n }\n}\n```\n\n---\n\n**Cursor**\n\nConfig file: `~/.cursor/mcp.json`\n\nOAuth:\n```json\n{\n \"mcpServers\": {\n \"gscServer\": {\n \"command\": \"/FULL/PATH/TO/uvx\",\n \"args\": [\"mcp-search-console\"],\n \"env\": {\n \"GSC_OAUTH_CLIENT_SECRETS_FILE\": \"/full/path/to/client_secrets.json\"\n }\n }\n }\n}\n```\n\n---\n\n**Codex CLI**\n\nConfig file: `~/.codex/config.toml`\n\nOAuth:\n```toml\n[mcp_servers.gscServer]\ncommand = \"/FULL/PATH/TO/uvx\"\nargs = [\"mcp-search-console\"]\nenabled = true\nenv = { GSC_OAUTH_CLIENT_SECRETS_FILE = \"/full/path/to/client_secrets.json\" }\n```\n\nService Account:\n```toml\n[mcp_servers.gscServer]\ncommand = \"/FULL/PATH/TO/uvx\"\nargs = [\"mcp-search-console\"]\nenabled = true\nenv = { GSC_CREDENTIALS_PATH = \"/full/path/to/service_account.json\", GSC_SKIP_OAUTH = \"true\" }\n```\n\n---\n\n> **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.\n>\n> **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.\n\nAfter saving the config, **fully quit the app (`Cmd+Q`) and reopen it**.\n\nFor 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.\n\n---\n\n#### Option B — Clone (Advanced)\n\n**Prefer a video walkthrough for this method?** The tutorial below covers the clone install path step by step — virtual environment setup, dependencies, and config:\n\n
\n \n \"Google\n \n
\n\nUse 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.\n\n> **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](https://www.python.org/downloads/) 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.\n\n**Clone the repo:**\n```bash\ngit clone https://github.com/AminForou/mcp-gsc.git\ncd mcp-gsc\n```\n\nOr download the ZIP from the green Code button at the top of this page and unzip it.\n\n**Set up the environment:**\n```bash\nuv venv .venv\nuv pip install -r requirements.txt\n```\n\n**Configure your AI client** (Claude Desktop example):\n\nOAuth:\n```json\n{\n \"mcpServers\": {\n \"gscServer\": {\n \"command\": \"/full/path/to/mcp-gsc/.venv/bin/python\",\n \"args\": [\"/full/path/to/mcp-gsc/gsc_server.py\"],\n \"env\": {\n \"GSC_OAUTH_CLIENT_SECRETS_FILE\": \"/full/path/to/client_secrets.json\"\n }\n }\n }\n}\n```\n\nService Account:\n```json\n{\n \"mcpServers\": {\n \"gscServer\": {\n \"command\": \"/full/path/to/mcp-gsc/.venv/bin/python\",\n \"args\": [\"/full/path/to/mcp-gsc/gsc_server.py\"],\n \"env\": {\n \"GSC_CREDENTIALS_PATH\": \"/full/path/to/service_account.json\",\n \"GSC_SKIP_OAUTH\": \"true\"\n }\n }\n }\n}\n```\n\nMac path examples:\n- Python: `/Users/yourname/Documents/mcp-gsc/.venv/bin/python`\n- Script: `/Users/yourname/Documents/mcp-gsc/gsc_server.py`\n\n---\n\n### Step 3 — Test\n\nAsk your AI assistant: **\"List my GSC properties\"**\n\nIf you see your properties — it's working. If not, ask: **\"Call get_capabilities\"** to see auth status and diagnose the issue.\n\n---\n\n## Environment Variables Reference\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `GSC_OAUTH_CLIENT_SECRETS_FILE` | OAuth only | — | Absolute path to your OAuth client secrets JSON. Always required when using `uvx`. |\n| `GSC_CREDENTIALS_PATH` | Service account only | — | Absolute path to your service account JSON key. Always required when using `uvx`. |\n| `GSC_SKIP_OAUTH` | No | `false` | Set to `\"true\"` to force service account auth and skip OAuth entirely |\n| `GSC_DATA_STATE` | No | `\"all\"` | `\"all\"` matches the GSC dashboard. `\"final\"` returns only confirmed data (2–3 day lag). |\n| `GSC_ALLOW_DESTRUCTIVE` | No | `false` | Set to `\"true\"` to enable add/delete site and delete sitemap tools |\n\n---\n\n## Cursor Marketplace\n\nOne-click install available — search for `mcp-search-console` in the Cursor Marketplace.\n\nAfter installing, configure your credentials (see Step 1 above) then use the bundled skills directly in Cursor Agent chat:\n\n| Skill | How to invoke | What it does |\n|---|---|---|\n| `seo-weekly-report` | *\"Run the SEO weekly report for example.com\"* | Full 28-day performance summary with period-over-period comparison and top queries |\n| `cannibalization-check` | *\"Check for keyword cannibalization on example.com\"* | Finds queries where multiple pages compete; recommends which to keep |\n| `indexing-audit` | *\"Audit indexing for my top pages\"* | Batch-inspects top 20 pages and returns a prioritized fix list |\n| `content-opportunities` | *\"Find content opportunities for example.com\"* | Surfaces position-11-20 queries with high impressions and low CTR |\n\n---\n\n## Sample Prompts\n\n| Tool | Sample Prompt |\n|------|--------------|\n| `list_properties` | \"List all my GSC properties and tell me which ones have the most pages indexed.\" |\n| `get_search_analytics` | \"Show me the top 20 search queries for mywebsite.com in the last 30 days, highlight any with CTR below 2%, and suggest title improvements.\" |\n| `get_performance_overview` | \"Create a visual performance overview of mywebsite.com for the last 28 days, identify any unusual drops or spikes, and explain possible causes.\" |\n| `check_indexing_issues` | \"Check these pages for indexing issues: mywebsite.com/product, mywebsite.com/services, mywebsite.com/about\" |\n| `inspect_url_enhanced` | \"Do a comprehensive inspection of mywebsite.com/landing-page and give me actionable recommendations.\" |\n| `compare_search_periods` | \"Compare my site's performance between January and February. What queries improved the most?\" |\n| `get_advanced_search_analytics` | \"Analyze queries with high impressions but positions below 10, filtered to mobile traffic in the US only.\" |\n\n---\n\n## Troubleshooting\n\n### `spawn uvx ENOENT` or `command not found: uvx`\n\nYour AI client can't find `uvx`. Use the full path instead of just `uvx`:\n\n```bash\n# Find your full path (macOS/Linux):\nwhich uvx\n# Typically: /Users/YOUR_NAME/.local/bin/uvx\n```\n\n```powershell\n# Find your full path (Windows PowerShell):\nGet-Command uvx | Select-Object -ExpandProperty Source\n# Typically: C:\\Users\\YOUR_NAME\\.local\\bin\\uvx.exe\n```\n\nReplace `\"command\": \"uvx\"` with the full path (e.g. `\"command\": \"/Users/YOUR_NAME/.local/bin/uvx\"`) in your config.\n\n### `uv --version` gives \"command not found\" right after installing\n\nThe installer updates `~/.local/bin` but your current Terminal session doesn't see it yet. Run:\n\n```bash\nsource $HOME/.local/bin/env\n```\n\nThen add it permanently:\n```bash\necho 'source $HOME/.local/bin/env' >> ~/.zshrc\n```\n\n### Authentication failed / credentials file not found\n\nMake sure you are using the **absolute path** to your credentials file — not a relative path, not `~/`. Example:\n```\n/Users/yourname/Documents/client_secrets.json ✅\n~/Documents/client_secrets.json ✅\nclient_secrets.json ❌\n```\n\n### MCP only works in Claude Desktop app, not the website\n\nThe MCP server runs locally on your machine. It only works in the **Claude Desktop app** (downloaded from [claude.ai/download](https://claude.ai/download)), not in the claude.ai browser interface.\n\n### AI Client Configuration Issues\n\n1. Make sure all file paths in your config are correct absolute paths\n2. Fully quit (`Cmd+Q`) and reopen the app after any config change — just closing the window is not enough\n3. Ask your AI assistant to \"call get_capabilities\" — it will report the exact auth status and error\n\n---\n\n## Safety: Destructive Operations\n\nBy default, `add_site`, `delete_site`, and `delete_sitemap` are disabled. To enable them:\n\n```json\n\"GSC_ALLOW_DESTRUCTIVE\": \"true\"\n```\n\n---\n\n## Remote Deployment & Docker (Advanced)\n\nThe 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.\n\n### HTTP Transport\n\n```bash\nMCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=3001 python gsc_server.py\n```\n\n| Variable | Default | Description |\n|---|---|---|\n| `MCP_TRANSPORT` | `stdio` | Set to `sse` for network/remote use |\n| `MCP_HOST` | `127.0.0.1` | Host to bind |\n| `MCP_PORT` | `3001` | Port to bind |\n\n### Docker\n\n```bash\ndocker build -t mcp-gsc .\n\ndocker run \\\n -e MCP_TRANSPORT=sse \\\n -e MCP_HOST=0.0.0.0 \\\n -e MCP_PORT=3001 \\\n -e GSC_CREDENTIALS_PATH=/app/credentials.json \\\n -v /path/to/credentials.json:/app/credentials.json \\\n -p 3001:3001 \\\n mcp-gsc\n```\n\n---\n\n## Related Tools\n\n**[Advanced GSC Visualizer](https://www.advancedgsc.com/?utm_source=github&utm_medium=readme&utm_campaign=mcp-gsc&utm_content=related-tools)** — 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 →](https://chromewebstore.google.com/detail/advanced-gsc-visualizer/cdiccpnglfpnclonhpchpaaoigfpieel)\n\n---\n\n## Contributing\n\nFound a bug or have an idea for improvement? Open an issue or submit a pull request on GitHub.\n\n---\n\n## License\n\nMIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## Changelog\n\n### [0.3.3] — July 2026\n- 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)\n\n### [0.3.2] — April 2026\n- **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.\n- **`get_capabilities` tool** — returns all available tools grouped by category plus live auth status in one call.\n- **Better auth error messages** — all tools now explicitly tell you to call `reauthenticate` when credentials are missing or expired.\n- **Improved `list_properties` description** — better semantic tool discovery in clients that use lazy tool loading.\n\n### [0.3.1] — April 2026\n- Fixed `list_properties` masking real auth errors; fail-fast on missing credentials.\n\n### [0.3.0] — April 2026\n- Cursor Marketplace plugin with 4 bundled SEO skills\n- Stable token storage in platform user config dir (survives `uvx` upgrades)\n- Structured JSON output for all data tools\n- 39 unit tests\n\n### [0.2.2] — April 2026\n- Safety mode for destructive tools (disabled by default)\n- HTTP/SSE transport for remote deployments\n- Dockerfile\n\n### [0.2.1] — March 2026\n- `reauthenticate` tool for switching Google accounts\n- Fixed sitemap TypeError crash\n- Fixed domain property 404 errors\n\n### [0.2.0] — March 2026\n- `dataState: \"all\"` by default (matches GSC dashboard)\n- Flexible `row_limit` parameter (up to 500)\n- Multi-dimension filtering for advanced analytics\n\n### [0.1.0] — Initial release\n- 19 tools covering property management, search analytics, URL inspection, and sitemap management\n- OAuth and service account authentication\n", "bytes": 19796, "sha": "6de977a53c6682a4d738cc8934f193a260c99bb8aac1500287590577803b44ba", "repo_slug": "aminforou/mcp-gsc", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_aminforou_mcp_gsc_search_console_mcp_a8a9b01f/readme" }