Google Search Console MCP

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, added GA4 tools. Works with Claude Desktop, Claude Code, Claude.ai, Codex, Cursor, and any MCP client. Only 100 seats.

→ Advanced GSC MCP (hosted)

---

What's New

[0.3.3] — July 2026

• 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.

[0.3.2] — April 2026

• 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.

---

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

| Tool | What It Does | What You Need to Provide |

|------|-------------|--------------------------|

| get_capabilities | Lists all tools and shows auth status — call this first if unsure | Nothing |

| list_properties | Shows all your GSC properties | Nothing |

| get_site_details | Details about a specific site | Site URL |

| get_search_analytics | Top queries and pages with clicks, impressions, CTR, position | Site URL, time period |

| get_performance_overview | Summary of site performance | Site URL, time period |

| compare_search_periods | Compare performance between two time periods | Site URL, two date ranges |

| get_search_by_page_query | Search terms driving traffic to a specific page | Site URL, page URL |

| get_advanced_search_analytics | Analytics with filters by country, device, query, page | Site URL |

| inspect_url_enhanced | Detailed crawl/index status for a URL | Site URL, page URL |

| batch_url_inspection | Inspect up to 10 URLs at once | Site URL, list of URLs |

| check_indexing_issues | Check multiple URLs for indexing problems | Site URL, list of URLs |

| get_sitemaps | Lists all sitemaps for a site | Site URL |

| list_sitemaps_enhanced | Detailed sitemap info including errors and warnings | Site URL |

| manage_sitemaps | Submit or delete sitemaps | Site URL, action |

| reauthenticate | Re-run the OAuth browser login (switch accounts) | Nothing |

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

---

<div align="center">

<a href="https://www.advancedgsc.com/mcp?utm_source=github&utm_medium=readme&utm_campaign=mcp-gsc&utm_content=banner">

<img src="assets/banner-1.jpg" alt="Skip setup — try the hosted MCP server with one-click Google sign-in. Works in ChatGPT and Claude web. Includes GA4 and advanced SEO tools." width="800" style="margin: 20px 0; border-radius: 8px;">

</a>

</div>

---

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

<div align="center">

<a href="https://www.youtube.com/watch?v=vhIOoD7B8Ow">

<img src="assets/seo-mcp-install-video-1.jpg" alt="GSC MCP Server Installation Guide 2026" width="600" style="margin: 20px 0; border-radius: 8px;">

</a>

</div>

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:

<div align="center">

<a href="https://youtu.be/PCWsK5BgSd0">

<img src="assets/gsc-mcp-seo-video-2.jpg" alt="Google Search Console API Setup Tutorial" width="600" style="margin: 20px 0; border-radius: 8px;">

</a>

</div>

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

| Variable | Required | Default | Description |

|---|---|---|---|

| GSC_OAUTH_CLIENT_SECRETS_FILE | OAuth only | — | Absolute path to your OAuth client secrets JSON. Always required when using uvx. |

| GSC_CREDENTIALS_PATH | Service account only | — | Absolute path to your service account JSON key. Always required when using uvx. |

| GSC_SKIP_OAUTH | No | false | Set to "true" to force service account auth and skip OAuth entirely |

| GSC_DATA_STATE | No | "all" | "all" matches the GSC dashboard. "final" returns only confirmed data (2–3 day lag). |

| GSC_ALLOW_DESTRUCTIVE | No | false | Set to "true" to enable add/delete site and delete sitemap tools |

---

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:

| Skill | How to invoke | What it does |

|---|---|---|

| seo-weekly-report | "Run the SEO weekly report for example.com" | Full 28-day performance summary with period-over-period comparison and top queries |

| cannibalization-check | "Check for keyword cannibalization on example.com" | Finds queries where multiple pages compete; recommends which to keep |

| indexing-audit | "Audit indexing for my top pages" | Batch-inspects top 20 pages and returns a prioritized fix list |

| content-opportunities | "Find content opportunities for example.com" | Surfaces position-11-20 queries with high impressions and low CTR |

---

Sample Prompts

| Tool | Sample Prompt |

|------|--------------|

| list_properties | "List all my GSC properties and tell me which ones have the most pages indexed." |

| 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." |

| get_performance_overview | "Create a visual performance overview of mywebsite.com for the last 28 days, identify any