gsc-mcp
Google Search Console 的本地 MCP server — 單一 Go binary,執行端零 runtime 依賴
繁體中文 | English |
Potencialize seu agente
Instalação do publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
Ainda não há uma versão empacotada no registro. Siga o README do repositório.
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
繁體中文 | English |
Google Search Console 的本地 MCP server — 純 Go 單一 binary、執行期零依賴,從使用者角度出發,一行安裝
給 SEO 與內容團隊設計:用你自己的 Google 帳號登入(ADC),本地 agent(Claude Code / Codex / Cursor / Hermes)就能查你本來就有權限的 Search Console 資料——不必為每個 property 加 service account。
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/geniushub-seo/gsc-mcp/main/install.sh | bash
gcloud auth login
gcloud projects list
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform
gcloud auth application-default set-quota-project PROJECT_ID
gcloud services enable searchconsole.googleapis.com --project=PROJECT_ID
gsc-mcp doctor
gsc-mcp setup
Windows(PowerShell)
irm https://raw.githubusercontent.com/geniushub-seo/gsc-mcp/main/install.ps1 | iex
gcloud auth login
gcloud projects list
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform
gcloud auth application-default set-quota-project PROJECT_ID
gcloud services enable searchconsole.googleapis.com --project=PROJECT_ID
gsc-mcp doctor
gsc-mcp setup
安裝腳本會下載對應平台 binary、驗證 SHA-256、裝到 ~/.local/bin(Windows 是 %LOCALAPPDATA%\Programs\gsc-mcp),並解除 macOS quarantine / Windows SmartScreen 封鎖標記。若由 AI agent 協助,所有終端指令(包括啟動 gcloud 登入)都由 agent 執行;使用者只需在自動開啟的 Google 網頁選帳號並按下允許,不必開啟終端或複製指令。詳見 INSTALL.md 與 Releases。
PROJECT_ID 換成 gcloud projects list 輸出裡的專案 ID,不要把佔位字原樣送出。那兩行都不能省——ADC 是個人帳號、不隸屬任何專案,少了 quota project 所有查詢會回 403 requires a quota project,看起來很像權限問題但不是;而全新的專案本來就沒有啟用 Search Console API,少了 gcloud services enable 會回同一個 403、細節裡寫 "reason": "SERVICE_DISABLED"。另外 gcloud auth login 跟 ADC 登入是兩次獨立登入,少了它 gcloud projects list 會說憑證過期。
裝完有任何一步不順,跑 gsc-mcp doctor——完整檢查加一次真實 list_sites,不寫任何檔案。
用你自己的 Google 帳號登入一次,MCP 設定不需要任何憑證環境變數。
手動安裝可跑上面的指令。若交給 AI agent,只要說「照 INSTALL.md 幫我裝好」;agent 必須負責所有終端操作,使用者只負責 Google 瀏覽器授權。
裝 gcloud(一次):
brew install --cask google-cloud-sdkNeed sudo access on macOS。改看下方「沒有 homebrew 的 macOS」。curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-latest-linux-x86_64.tar.gz && tar -xf google-cloud-cli-latest-linux-x86_64.tar.gz && ./google-cloud-sdk/install.sh(或發行版套件 google-cloud-sdk)winget install Google.CloudSDK,或下載 GoogleCloudSDKInstaller.exe沒有 homebrew 的 macOS——gcloud 是 Python 寫的,而 macOS 內建的 /usr/bin/python3 是 3.9.6,低於 gcloud 要求的 3.10。連 install.sh 自己都跑不起來(它本身就是 Python 程式),所以不是「解壓後補跑 install.sh」就能解決,得先備好一個夠新的 Python:
# 1. 找一個 3.10 以上的 python3
for p in python3.13 python3.12 python3.11 python3.10 "$HOME"/.local/share/uv/python/*/bin/python3; do
c=$(command -v "$p" 2>/dev/null) || { [ -x "$p" ] && c="$p"; } || continue
"$c" -c 'import sys;sys.exit(0 if sys.version_info>=(3,10) else 1)' 2>/dev/null && { echo "FOUND: $c"; break; }
done
# 2. 找不到就用 uv 裝一個(不需要管理員權限),裝完重跑步驟 1 取得路徑
curl -LsSf https://astral.sh/uv/install.sh | sh
"$HOME/.local/bin/uv" python install 3.12
# 3. 用它安裝 gcloud(Intel Mac 把 darwin-arm 換成 darwin-x86_64)
export CLOUDSDK_PYTHON=<步驟 1 找到的路徑>
tmp=$(mktemp -d)
curl -fsSL https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz -o "$tmp/gcloud.tar.gz"
mkdir -p "$HOME/.local/share" && tar -xzf "$tmp/gcloud.tar.gz" -C "$HOME/.local/share"
"$HOME/.local/share/google-cloud-sdk/install.sh" --quiet --path-update=false
這條路裝好之後,下面每一條 gcloud 指令都要帶著 CLOUDSDK_PYTHON(寫進 shell profile 或逐條 export)。用 homebrew 裝的則不需要。
啟用 Search Console API(若尚未):於 API Library 按 Enable。先確認左上角選到的是你要用的專案,並記下它的專案 ID(小寫那串,不是顯示名稱)。
ADC 登入(會開瀏覽器)——上面第二行。
設 quota project——上面第三行。ADC 必做,漏掉每次查詢都會 403。
跑 gsc-mcp setup——合併 MCP 設定並試呼叫 list_sites。
在 agent 裡呼叫 list_sites 確認看得到哪些 property。
出問題時跑 gsc-mcp doctor:完整檢查加一次真實 list_sites,不寫任何檔案,並針對失敗原因給出對應指令(缺 quota project、token 失效、API 未啟用各有各的處置)。setup --dry-run 會跳過 API 呼叫,答不出憑證能不能用,別拿它當診斷工具。
{
"mcpServers": {
"gsc": {
"command": "/Users/YOUR_USER/.local/bin/gsc-mcp"
}
}
}
憑證自動從 ~/.config/gcloud/application_default_credentials.json 讀取。
會因改密碼、久未使用、組織政策而失效。重新登入即可,不是程式壞了:
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform
寫入有兩道獨立閘門,ADC 兩道都要過:
GSC_ENABLE_WRITE=true。這是 gsc-mcp 的本地閘門,對 ADC 與 service account 都生效。只重登 write scope 不夠。webmasters scope(事後無法擴大)。重跑登入並帶上:gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/cloud-platform
(webmasters 含讀寫;唯讀請用 webmasters.readonly。)
ADC 不需要設任何憑證變數——照上面裝好,binary 會自己讀
~/.config/gcloud/application_default_credentials.json。下表全部是選填。
service account 的憑證變數與完整優先序見下方「進階:service account(headless / CI)」;一般安裝不需要。
install.sh 會嘗試移除 quarantine。若你是從瀏覽器手動下載 binary,仍可能看到「無法驗證開發者」:Finder 對該檔右鍵 → 打開 → 打開。本專案不做 Apple 程式碼簽章。
一般使用者不需要這節。 只有下列情況才走這條路:手上已經有 service account JSON key、跑在 CI 或無人機器上、目標機器開不了瀏覽器、或需要非人類身分。否則請用上方的 ADC——它不必為每個 property 加使用者。
代價先講明:service account 是機器帳號,GSC 不會自動認它,每一個要查的 property
都得手動把它的 client_email 加成使用者。換來的是寫入比 ADC 單純:GSC_ENABLE_WRITE=true
會直接把 scope 升級為 webmasters,不必像 ADC 那樣重跑登入。
client_email 加成使用者。{
"mcpServers": {
"gsc": {
"command": "/Users/YOUR_USER/bin/gsc-mcp",
"env": {
"GOOGLE_SERVICE_ACCOUNT_FILE": "/Users/YOUR_USER/.config/gsc-mcp/service-account.json"
}
}
}
}
mkdir -p ~/.config/gsc-mcp && chmod 700 ~/.config/gsc-mcp
chmod 600 ~/.config/gsc-mcp/service-account.json
完整優先序(前五層都是顯式指定,全都沒設才落到 ADC):--credentials-file
(別名 --service-account-file)→ GOOGLE_APPLICATION_CREDENTIALS →
GOOGLE_SERVICE_ACCOUNT_FILE → GOOGLE_SERVICE_ACCOUNT_JSON → .env →
ADC 預設路徑。權威定義見 SPEC.md §4.2。
想讓 agent 讀到專案專屬設定與教學時,clone 此 repo。這些設定都不含憑證或本機絕對路徑。
所有 client 的共同驗收:先跑 gsc-mcp doctor,再叫 agent 呼叫 list_sites。不要把 OAuth token 或 service-account key 放入這些檔案。
六個 skill 隨 server 附上,不用自己想 prompt:
Claude Code plugin 與 Codex 都會讀取共用的 .agents/skills/。Cursor 有同一套安全預設的 project rule;需要特定分析時,agent 可讀對應的 SKILL.md。
curl | bash 安裝會一併裝 skill(v0.6.0 起):binary 裝好後 installer 會下載
gsc-mcp-skills.tar.gz(同一份 checksums.txt 驗)解到 ~/.claude/skills/。三條規則:
monthly-report,它就原封不動留著,只印一行 keep。
改過的本地版本不會被蓋掉——但這也表示升級不會換到新版 skill。要拿新版,先把
~/.claude/skills/ 底下該支目錄移走再重跑 installer。~/.claude/ 已存在時才裝,不對沒在用 Claude Code 的人寫東西進家目錄。
--with-skills 強制裝,--no-skills 完全不裝。只有九支是刻意的。總覽、逐頁拆解、「進階」分析其實是同一個 API 呼叫的不同預設參數,各做一支的代價是每次請求都要把所有 schema 傳給 LLM,選錯的機率也跟著上升。那些情況交給 gsc-recipes 這張路由表,不佔 context。只有 LLM 自己做不到的運算才值得包成 tool——後面三支就是這條線的另一邊:對最多 25,000 列算中位數基準、跨兩期逐頁歸因,那不是 LLM 讀得完的算術。
那三支只回事實與算術,不給建議。判讀規則在 ctr-gaps 與 traffic-decline-diagnosis 兩支 skill 裡——沒有規則就照數字給建議,會踩雷(例如基準 CTR 本來就只有 1% 的字,改標題不會有點擊)。
sites.add / sites.delete:add 後仍需在 UI 驗證,delete 誤刪風險過高。JobPosting 與 BroadcastEvent 開放。rowLimit 上限 25,000(後台介面一次只給 1,000,這是用 API 的主要好處)。超過要用 startRow 分頁。HOUR 維度必須搭配 dataState: HOURLY_ALL,且只有近 10 天資料。QUERY / PAGE / COUNTRY / DEVICE / SEARCH_APPEARANCE,不能 filter DATE 或 HOUR。page,aggregationType 不能用 BY_PROPERTY。site_url 可以直接給裸網域(example.com)、完整 URL 或標準 sc-domain: 格式,server 會正規化;猜錯導致 403 時會自動查詢可存取的 property 重試一次。
go build -trimpath -ldflags="-s -w -X main.version=dev" -o ./bin/gsc-mcp ./cmd/gsc-mcp
go test ./... && go vet ./... && golangci-lint run
由 萬智匯 Genius Hub 開發,在我們自己的 SEO 與 GEO 客戶專案裡每天在跑 · 採 MIT 授權
SEO 與 GEO(讓 AI 回答時引用你的內容)實作分享 → Super Simple Marketing
Google Search Console 的本地 MCP server — 純 Go 單一 binary、執行期零依賴,從使用者角度出發,一行安裝
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
Gsc roda localmente via stdio.
Última verificação: 2026-11-15. Google Search Console 的本地 MCP server — 純 Go 單一 binary、執行期零依賴,從使用者角度出發,一行安裝