Skip to content
Back to search

mcp-gsc

Google Search Console Insights with Claude AI for SEOs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aminforou--mcp-gsc/badge.svg)](/listings/aminforou--mcp-gsc)

HTML

<a href="/listings/aminforou--mcp-gsc"><img src="/api/listings/aminforou--mcp-gsc/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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](https://console.cloud.google.com/) and create or select a project 2. [Enable the Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com) 3. Go to [Credentials](https://console.cloud.google.com/apis/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](https://console.cloud.google.com/) and create or select a project 2. [Enable the Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com) 3. Go to [Credentials](https://console.cloud.google.com/apis/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"> </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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "mcp-search-console",
  3. "displayName": "Search Console MCP",
  4. "version": "0.3.0",
  5. "description": "Connect Google Search Console to Claude Code. Query SEO data, inspect URLs, audit indexing, and identify content opportunities through natural language.",
  6. "author": {
  7. "name": "Amin Foroutan"
  8. },
  9. "license": "MIT",
  10. "homepage": "https://advancedgsc.com",
  11. "repository": "https://github.com/AminForou/mcp-gsc",
  12. "keywords": ["seo", "google-search-console", "analytics", "mcp", "gsc"],
  13. "logo": "./assets/logo.png",
  14. "skills": "./skills/",
  15. "mcpServers": "./.mcp.json"
  16. }
README.md · README · 530 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Google Search Console MCP Server for SEOs
  2. A 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.
  3. > **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.
  4. > → [**Advanced MCP for SEO professionals (hosted)**](https://www.advancedgsc.com/mcp?utm_source=github&utm_medium=readme&utm_campaign=mcp-gsc&utm_content=hero-callout)
  5. ---
  6. ## What's New
  7. ### [0.4.2] — November 2026
  8. - **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](https://github.com/christian-fastcorp). (#56)
  9. - **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](https://github.com/kuldiph). (#52)
  10. - **`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](https://github.com/dajiaohuang). (#62)
  11. - **Optional tool arguments accept an explicit `null`** — nine `str | None` parameters now validate when a client sends the advertised `null` default. Thanks [@vishalhabib99](https://github.com/vishalhabib99). (#58)
  12. - **Raised the `mcp[cli]` floor to `>=1.27.2`** (kept the `<2.0.0` cap) to clear four published SDK advisories. Thanks [@prateekparshwa](https://github.com/prateekparshwa). (#40)
  13. See the full version history in the [Changelog](#changelog) below.
  14. ---
  15. ## What Can This Do?
  16. **Property Management**
  17. - See all your GSC properties in one place
  18. - Get verification details and ownership information
  19. - Add or remove properties from your account
  20. **Search Analytics & Reporting**
  21. - Discover which queries bring visitors to your site
  22. - Track impressions, clicks, and click-through rates
  23. - Analyze performance trends and compare time periods
  24. - Visualize data with charts created by your AI assistant
  25. **URL Inspection & Indexing**
  26. - Check if specific pages have indexing problems
  27. - See when Google last crawled your pages
  28. - Inspect multiple URLs at once to identify patterns
  29. **Sitemap Management**
  30. - View all sitemaps and their status
  31. - Submit new sitemaps
  32. - Check for errors or warnings
  33. ---
  34. ## Available Tools
  35. | Tool | What It Does | What You Need to Provide |
  36. |------|-------------|--------------------------|
  37. | `get_capabilities` | Lists all tools and shows auth status — call this first if unsure | Nothing |
  38. | `list_properties` | Shows all your GSC properties | Nothing |
  39. | `get_site_details` | Details about a specific site | Site URL |
  40. | `get_search_analytics` | Top queries and pages with clicks, impressions, CTR, position | Site URL, time period |
  41. | `get_performance_overview` | Summary of site performance | Site URL, time period |
  42. | `compare_search_periods` | Compare performance between two time periods | Site URL, two date ranges |
  43. | `get_search_by_page_query` | Search terms driving traffic to a specific page | Site URL, page URL |
  44. | `get_advanced_search_analytics` | Analytics with filters by country, device, query, page | Site URL |
  45. | `inspect_url_enhanced` | Detailed crawl/index status for a URL | Site URL, page URL |
  46. | `batch_url_inspection` | Inspect up to 10 URLs at once | Site URL, list of URLs |
  47. | `check_indexing_issues` | Check multiple URLs for indexing problems | Site URL, list of URLs |
  48. | `get_sitemaps` | Lists all sitemaps for a site | Site URL |
  49. | `list_sitemaps_enhanced` | Detailed sitemap info including errors and warnings | Site URL |
  50. | `manage_sitemaps` | Submit or delete sitemaps | Site URL, action |
  51. | `reauthenticate` | Re-run the OAuth browser login (switch accounts) | Nothing |
  52. *Ask your AI assistant to "call get_capabilities" for the full list of all 20 tools.*
  53. ---
  54. <div align="center">
  55. <a href="https://www.advancedgsc.com/mcp?utm_source=github&utm_medium=readme&utm_campaign=mcp-gsc&utm_content=banner">
  56. <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;">
  57. </a>
  58. </div>
  59. ---
  60. ## Getting Started
  61. ### Step 1 — Set Up Google API Credentials
  62. You need credentials before configuring any client. Pick one method:
  63. #### Option A — OAuth (Recommended — uses your own Google account)
  64. 1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create or select a project
  65. 2. [Enable the Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)
  66. 3. Go to [Credentials](https://console.cloud.google.com/apis/credentials) → Create Credentials → **OAuth client ID**
  67. 4. Configure the OAuth consent screen, select **Desktop app**, click Create
  68. 5. Download the JSON file — save it somewhere permanent (e.g. `~/Documents/client_secrets.json`)
  69. 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.
  70. #### Option B — Service Account (For automation or team use)
  71. 1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create or select a project
  72. 2. [Enable the Search Console API](https://console.cloud.google.com/apis/library/searchconsole.googleapis.com)
  73. 3. Go to [Credentials](https://console.cloud.google.com/apis/credentials) → Create Credentials → **Service Account**
  74. 4. Go to the Keys tab → Add Key → Create new key → JSON → Download
  75. 5. Save the file somewhere permanent (e.g. `~/Documents/service_account.json`)
  76. 6. Add the service account email to your GSC property: Search Console → Settings → Users and permissions → Add user → Full access
  77. #### 🎥 Watch the step-by-step setup tutorial for this section
  78. <div align="center">
  79. <a href="https://www.youtube.com/watch?v=vhIOoD7B8Ow">
  80. <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;">
  81. </a>
  82. </div>
  83. *Updated 2026 — covers the full installation process using the new uvx method, from setting up your Google credentials to your first successful query.*
  84. ---
  85. ### Step 2 — Installation
  86. #### Option A — uvx (Recommended)
  87. No cloning, no Python installation, no virtual environments. `uvx` downloads and runs the server automatically and keeps it up to date.
  88. **Install uv** — open Terminal and run all three commands in order:
  89. ```bash
  90. # 1. Download and install
  91. curl -LsSf https://astral.sh/uv/install.sh | sh
  92. # 2. Activate in the current Terminal session
  93. source $HOME/.local/bin/env
  94. # 3. Make it permanent for all future sessions
  95. echo 'source $HOME/.local/bin/env' >> ~/.zshrc
  96. ```
  97. Verify:
  98. ```bash
  99. uv --version
  100. ```
  101. > **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.
  102. Now configure your AI client:
  103. ---
  104. **Claude Desktop**
  105. Config file: `~/Library/Application Support/Claude/claude_desktop_config.json`
  106. OAuth:
  107. ```json
  108. {
  109. "mcpServers": {
  110. "gscServer": {
  111. "command": "/FULL/PATH/TO/uvx",
  112. "args": ["mcp-search-console"],
  113. "env": {
  114. "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
  115. }
  116. }
  117. }
  118. }
  119. ```
  120. Service Account:
  121. ```json
  122. {
  123. "mcpServers": {
  124. "gscServer": {
  125. "command": "/FULL/PATH/TO/uvx",
  126. "args": ["mcp-search-console"],
  127. "env": {
  128. "GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
  129. "GSC_SKIP_OAUTH": "true"
  130. }
  131. }
  132. }
  133. }
  134. ```
  135. ---
  136. **Cursor**
  137. Config file: `~/.cursor/mcp.json`
  138. OAuth:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "gscServer": {
  143. "command": "/FULL/PATH/TO/uvx",
  144. "args": ["mcp-search-console"],
  145. "env": {
  146. "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
  147. }
  148. }
  149. }
  150. }
  151. ```
  152. ---
  153. **Codex CLI**
  154. Config file: `~/.codex/config.toml`
  155. OAuth:
  156. ```toml
  157. [mcp_servers.gscServer]
  158. command = "/FULL/PATH/TO/uvx"
  159. args = ["mcp-search-console"]
  160. enabled = true
  161. env = { GSC_OAUTH_CLIENT_SECRETS_FILE = "/full/path/to/client_secrets.json" }
  162. ```
  163. Service Account:
  164. ```toml
  165. [mcp_servers.gscServer]
  166. command = "/FULL/PATH/TO/uvx"
  167. args = ["mcp-search-console"]
  168. enabled = true
  169. env = { GSC_CREDENTIALS_PATH = "/full/path/to/service_account.json", GSC_SKIP_OAUTH = "true" }
  170. ```
  171. ---
  172. > **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.
  173. >
  174. > **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.
  175. After saving the config, **fully quit the app (`Cmd+Q`) and reopen it**.
  176. 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.
  177. ---
  178. #### Option B — Clone (Advanced)
  179. **Prefer a video walkthrough for this method?** The tutorial below covers the clone install path step by step — virtual environment setup, dependencies, and config:
  180. <div align="center">
  181. <a href="https://youtu.be/PCWsK5BgSd0">
  182. <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;">
  183. </a>
  184. </div>
  185. 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.
  186. > **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.
  187. **Clone the repo:**
  188. ```bash
  189. git clone https://github.com/AminForou/mcp-gsc.git
  190. cd mcp-gsc
  191. ```
  192. Or download the ZIP from the green Code button at the top of this page and unzip it.
  193. **Set up the environment:**
  194. ```bash
  195. uv venv .venv
  196. uv pip install -r requirements.txt
  197. ```
  198. **Configure your AI client** (Claude Desktop example):
  199. OAuth:
  200. ```json
  201. {
  202. "mcpServers": {
  203. "gscServer": {
  204. "command": "/full/path/to/mcp-gsc/.venv/bin/python",
  205. "args": ["/full/path/to/mcp-gsc/gsc_server.py"],
  206. "env": {
  207. "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
  208. }
  209. }
  210. }
  211. }
  212. ```
  213. Service Account:
  214. ```json
  215. {
  216. "mcpServers": {
  217. "gscServer": {
  218. "command": "/full/path/to/mcp-gsc/.venv/bin/python",
  219. "args": ["/full/path/to/mcp-gsc/gsc_server.py"],
  220. "env": {
  221. "GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
  222. "GSC_SKIP_OAUTH": "true"
  223. }
  224. }
  225. }
  226. }
  227. ```
  228. Mac path examples:
  229. - Python: `/Users/yourname/Documents/mcp-gsc/.venv/bin/python`
  230. - Script: `/Users/yourname/Documents/mcp-gsc/gsc_server.py`
  231. ---
  232. ### Step 3 — Test
  233. Ask your AI assistant: **"List my GSC properties"**
  234. If you see your properties — it's working. If not, ask: **"Call get_capabilities"** to see auth status and diagnose the issue.
  235. ---
  236. ## Environment Variables Reference
  237. | Variable | Required | Default | Description |
  238. |---|---|---|---|
  239. | `GSC_OAUTH_CLIENT_SECRETS_FILE` | OAuth only | — | Absolute path to your OAuth client secrets JSON. Always required when using `uvx`. |
  240. | `GSC_CREDENTIALS_PATH` | Service account only | — | Absolute path to your service account JSON key. Always required when using `uvx`. |
  241. | `GSC_SKIP_OAUTH` | No | `false` | Set to `"true"` to force service account auth and skip OAuth entirely |
  242. | `GSC_DATA_STATE` | No | `"all"` | `"all"` matches the GSC dashboard. `"final"` returns only confirmed data (2–3 day lag). |
  243. | `GSC_ALLOW_DESTRUCTIVE` | No | `false` | Set to `"true"` to enable add/delete site and delete sitemap tools |
  244. ---
  245. ## Cursor Marketplace
  246. One-click install available — search for `mcp-search-console` in the Cursor Marketplace.
  247. After installing, configure your credentials (see Step 1 above) then use the bundled skills directly in Cursor Agent chat:
  248. | Skill | How to invoke | What it does |
  249. |---|---|---|
  250. | `seo-weekly-report` | *"Run the SEO weekly report for example.com"* | Full 28-day performance summary with period-over-period comparison and top queries |
  251. | `cannibalization-check` | *"Check for keyword cannibalization on example.com"* | Finds queries where multiple pages compete; recommends which to keep |
  252. | `indexing-audit` | *"Audit indexing for my top pages"* | Batch-inspects top 20 pages and returns a prioritized fix list |
  253. | `content-opportunities` | *"Find content opportunities for example.com"* | Surfaces position-11-20 queries with high impressions and low CTR |
  254. ---
  255. ## Sample Prompts
  256. | Tool | Sample Prompt |
  257. |------|--------------|
  258. | `list_properties` | "List all my GSC properties and tell me which ones have the most pages indexed." |
  259. | `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." |
  260. | `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." |
  261. | `check_indexing_issues` | "Check these pages for indexing issues: mywebsite.com/product, mywebsite.com/services, mywebsite.com/about" |
  262. | `inspect_url_enhanced` | "Do a comprehensive inspection of mywebsite.com/landing-page and give me actionable recommendations." |
  263. | `compare_search_periods` | "Compare my site's performance between January and February. What queries improved the most?" |
  264. | `get_advanced_search_analytics` | "Analyze queries with high impressions but positions below 10, filtered to mobile traffic in the US only." |
  265. ---
  266. ## Troubleshooting
  267. ### `spawn uvx ENOENT` or `command not found: uvx`
  268. Your AI client can't find `uvx`. Use the full path instead of just `uvx`:
  269. ```bash
  270. # Find your full path (macOS/Linux):
  271. which uvx
  272. # Typically: /Users/YOUR_NAME/.local/bin/uvx
  273. ```
  274. ```powershell
  275. # Find your full path (Windows PowerShell):
  276. Get-Command uvx | Select-Object -ExpandProperty Source
  277. # Typically: C:\Users\YOUR_NAME\.local\bin\uvx.exe
  278. ```
  279. Replace `"command": "uvx"` with the full path (e.g. `"command": "/Users/YOUR_NAME/.local/bin/uvx"`) in your config.
  280. ### `uv --version` gives "command not found" right after installing
  281. The installer updates `~/.local/bin` but your current Terminal session doesn't see it yet. Run:
  282. ```bash
  283. source $HOME/.local/bin/env
  284. ```
  285. Then add it permanently:
  286. ```bash
  287. echo 'source $HOME/.local/bin/env' >> ~/.zshrc
  288. ```
  289. ### Authentication failed / credentials file not found
  290. Make sure you are using the **absolute path** to your credentials file — not a relative path, not `~/`. Example:
  291. ```
  292. /Users/yourname/Documents/client_secrets.json ✅
  293. ~/Documents/client_secrets.json ✅
  294. client_secrets.json ❌
  295. ```
  296. ### MCP only works in Claude Desktop app, not the website
  297. The 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.
  298. ### AI Client Configuration Issues
  299. 1. Make sure all file paths in your config are correct absolute paths
  300. 2. Fully quit (`Cmd+Q`) and reopen the app after any config change — just closing the window is not enough
  301. 3. Ask your AI assistant to "call get_capabilities" — it will report the exact auth status and error
  302. ---
  303. ## Safety: Destructive Operations
  304. By default, `add_site`, `delete_site`, and `delete_sitemap` are disabled. To enable them:
  305. ```json
  306. "GSC_ALLOW_DESTRUCTIVE": "true"
  307. ```
  308. ---
  309. ## Remote Deployment & Docker (Advanced)
  310. 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.
  311. ### HTTP Transport
  312. ```bash
  313. MCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=3001 python gsc_server.py
  314. ```
  315. | Variable | Default | Description |
  316. |---|---|---|
  317. | `MCP_TRANSPORT` | `stdio` | Set to `sse` for network/remote use |
  318. | `MCP_HOST` | `127.0.0.1` | Host to bind |
  319. | `MCP_PORT` | `3001` | Port to bind |
  320. ### Docker
  321. ```bash
  322. docker build -t mcp-gsc .
  323. docker run \
  324. -e MCP_TRANSPORT=sse \
  325. -e MCP_HOST=0.0.0.0 \
  326. -e MCP_PORT=3001 \
  327. -e GSC_CREDENTIALS_PATH=/app/credentials.json \
  328. -v /path/to/credentials.json:/app/credentials.json \
  329. -p 3001:3001 \
  330. mcp-gsc
  331. ```
  332. ---
  333. ## Related Tools
  334. **[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)
  335. ---
  336. ## Contributing
  337. Found a bug or have an idea for improvement? Open an issue or submit a pull request on GitHub.
  338. Thanks to everyone who has reported issues and contributed fixes, including
  339. [@patrickweh](https://github.com/patrickweh), [@remotesensei](https://github.com/remotesensei),
  340. [@JKdreaming](https://github.com/JKdreaming), and [@kuldiph](https://github.com/kuldiph).
  341. ---
  342. ## License
  343. MIT License. See the [LICENSE](LICENSE) file for details.
  344. ---
  345. ## Changelog
  346. ### [0.4.2] — November 2026
  347. - 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](https://github.com/christian-fastcorp))
  348. - 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](https://github.com/kuldiph))
  349. - 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](https://github.com/dajiaohuang))
  350. - 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](https://github.com/vishalhabib99))
  351. - 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](https://github.com/prateekparshwa))
  352. ### [0.4.1] — September 2026
  353. - `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](https://github.com/kuldiph))
  354. - 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](https://github.com/kuldiph))
  355. ### [0.4.0] — September 2026
  356. - 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](https://github.com/patrickweh))
  357. - `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](https://github.com/remotesensei))
  358. - `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](https://github.com/JKdreaming))
  359. - `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](https://github.com/kuldiph))
  360. - Replaced three bare `except:` clauses with `except Exception:` so `KeyboardInterrupt`/`SystemExit` are no longer swallowed. (Fixes #53; thanks [@kuldiph](https://github.com/kuldiph))
  361. - **Breaking:** `batch_url_inspection` renames the per-URL `verdict` field to `index_verdict`.
  362. ### [0.3.3] — July 2026
  363. - 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)
  364. ### [0.3.2] — April 2026
  365. - **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.
  366. - **`get_capabilities` tool** — returns all available tools grouped by category plus live auth status in one call.
  367. - **Better auth error messages** — all tools now explicitly tell you to call `reauthenticate` when credentials are missing or expired.
  368. - **Improved `list_properties` description** — better semantic tool discovery in clients that use lazy tool loading.
  369. ### [0.3.1] — April 2026
  370. - Fixed `list_properties` masking real auth errors; fail-fast on missing credentials.
  371. ### [0.3.0] — April 2026
  372. - Cursor Marketplace plugin with 4 bundled SEO skills
  373. - Stable token storage in platform user config dir (survives `uvx` upgrades)
  374. - Structured JSON output for all data tools
  375. - 39 unit tests
  376. ### [0.2.2] — April 2026
  377. - Safety mode for destructive tools (disabled by default)
  378. - HTTP/SSE transport for remote deployments
  379. - Dockerfile
  380. ### [0.2.1] — March 2026
  381. - `reauthenticate` tool for switching Google accounts
  382. - Fixed sitemap TypeError crash
  383. - Fixed domain property 404 errors
  384. ### [0.2.0] — March 2026
  385. - `dataState: "all"` by default (matches GSC dashboard)
  386. - Flexible `row_limit` parameter (up to 500)
  387. - Multi-dimension filtering for advanced analytics
  388. ### [0.1.0] — Initial release
  389. - 19 tools covering property management, search analytics, URL inspection, and sitemap management
  390. - OAuth and service account authentication

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.