給 SEO 與內容團隊設計：用你自己的 Google 帳號登入（ADC），本地 agent（Claude Code / Codex / Cursor）就能查你本來就有權限的 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，不寫任何檔案。

開始使用（ADC，主推）

用你自己的 Google 帳號登入一次，MCP 設定不需要任何憑證環境變數。

手動安裝可跑上面的指令。若交給 AI agent，只要說「照 INSTALL.md 幫我裝好」；agent 必須負責所有終端操作，使用者只負責 Google 瀏覽器授權。

自己動手（已裝 binary 之後）

1. 裝 gcloud（一次）：

   • macOS（已有 homebrew）：brew install --cask google-cloud-sdk
   • macOS（沒有 homebrew）：不要為此去裝 homebrew——裝它要求你的帳號是本機管理員，公司配發的電腦常常不是，會停在 Need sudo access on macOS。改看下方「沒有 homebrew 的 macOS」。
   • Linux：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）
   • Windows：winget install Google.CloudSDK，或下載 GoogleCloudSDKInstaller.exe
   • 那 713 MB 是 Google Cloud SDK 的大小，不是本專案的。

   沒有 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 裝的則不需要。

2. 啟用 Search Console API（若尚未）：於 API Library 按 Enable。先確認左上角選到的是你要用的專案，並記下它的專案 ID（小寫那串，不是顯示名稱）。

3. ADC 登入（會開瀏覽器）——上面第二行。

4. 設 quota project——上面第三行。ADC 必做，漏掉每次查詢都會 403。

5. 跑 gsc-mcp setup——合併 MCP 設定並試呼叫 list_sites。

6. 在 agent 裡呼叫 list_sites 確認看得到哪些 property。

出問題時跑 gsc-mcp doctor：完整檢查加一次真實 list_sites，不寫任何檔案，並針對失敗原因給出對應指令（缺 quota project、token 失效、API 未啟用各有各的處置）。setup --dry-run 會跳過 API 呼叫，答不出憑證能不能用，別拿它當診斷工具。

MCP 設定長這樣（ADC：只要 command）

{
  "mcpServers": {
    "gsc": {
      "command": "/Users/YOUR_USER/.local/bin/gsc-mcp"
    }
  }
}

憑證自動從 ~/.config/gcloud/application_default_credentials.json 讀取。

ADC refresh token 失效時

會因改密碼、久未使用、組織政策而失效。重新登入即可，不是程式壞了：

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform

寫入（submit / delete sitemap）與 ADC

寫入有兩道獨立閘門，ADC 兩道都要過：

1. 設定 GSC_ENABLE_WRITE=true。這是 gsc-mcp 的本地閘門，對 ADC 與 service account 都生效。只重登 write scope 不夠。
2. ADC token 還必須在登入當下就帶 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）」；一般安裝不需要。

macOS Gatekeeper

install.sh 會嘗試移除 quarantine。若你是從瀏覽器手動下載 binary，仍可能看到「無法驗證開發者」：Finder 對該檔右鍵 → 打開 → 打開。本專案不做 Apple 程式碼簽章。

進階：service account（headless / CI）

一般使用者不需要這節。 只有下列情況才走這條路：手上已經有 service account JSON
key、跑在 CI 或無人機器上、目標機器開不了瀏覽器、或需要非人類身分。否則請用上方的
ADC——它不必為每個 property 加使用者。

代價先講明：service account 是機器帳號，GSC 不會自動認它，每一個要查的 property
都得手動把它的 client_email 加成使用者。換來的是寫入比 ADC 單純：GSC_ENABLE_WRITE=true
會直接把 scope 升級為 webmasters，不必像 ADC 那樣重跑登入。

1. GCP 啟用 Search Console API → 建 service account → 下載 JSON key。
2. 到 Search Console 每個 property 把 client_email 加成使用者。
3. MCP 設定加上 env：

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

service account 專用變數與憑證優先序

完整優先序（前五層都是顯式指定，全都沒設才落到 ADC）：--credentials-file
（別名 --service-account-file）→ GOOGLE_APPLICATION_CREDENTIALS →
GOOGLE_SERVICE_ACCOUNT_FILE → GOOGLE_SERVICE_ACCOUNT_JSON → .env →
ADC 預設路徑。權威定義見 SPEC.md §4.2。

各 agent 的原生上手方式

想讓 agent 讀到專案專屬設定與教學時，clone 此 repo。這些設定都不含憑證或本機絕對路徑。

所有 client 的共同驗收：先跑 gsc-mcp doctor，再叫 agent 呼叫 list_sites。不要把 OAuth token 或 service-account key 放入這些檔案。

Skills（開箱即用的分析）

六個 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 完全不裝。
• 舊版 release 沒有這個資產也不會失敗，只印一行警告，binary 照樣裝好。

工具清單

只有九支是刻意的。總覽、逐頁拆解、「進階」分析其實是同一個 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 誤刪風險過高。
• Indexing API：Google 只對 JobPosting 與 BroadcastEvent 開放。
• 涵蓋範圍報告、Core Web Vitals、連結報告：官方 API 不存在。

資料特性（這些都寫進了 LLM 讀的 tool description）

• 日期是 PT 時區（UTC−7/−8），不是 UTC 也不是台北時間。
• 資料有 2–4 天延遲，只保留 16 個月；近期日期可能回傳不完整資料。
• API 只回傳 top rows，不保證完整；加總不會等於後台的總計。
• rowLimit 上限 25,000（後台介面一次只給 1,000，這是用 API 的主要好處）。超過要用 startRow 分頁。
• HOUR 維度必須搭配 dataState: HOURLY_ALL，且只有近 10 天資料。
• filter 只能作用於 QUERY / PAGE / COUNTRY / DEVICE / SEARCH_APPEARANCE，不能 filter DATE 或 HOUR。
• 若 group 或 filter 了 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

相關文件

• INSTALL.md — 寫給 AI agent 照著跑的安裝指引
• SPEC.md — 定稿技術規格