試用 Google Analytics 的 MCP 伺服器。從 GitHub 安裝，詳情請參閱公告。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

試用 Google Analytics MCP 伺服器

Google Analytics Model Context Protocol (MCP) 伺服器可讓您將 Google Analytics 資料連結至大型語言模型 (LLM) 和 AI 代理 (例如 Gemini)。您可以使用 MCP 伺服器，以自然語言查詢報表、檢查資源設定，以及建構自訂 Analytics 代理。

設定 MCP 伺服器前往 GitHub 查看觀看設定教學課程

必要條件

設定 Google Analytics MCP 伺服器前，請先完成下列要求：

安裝 Python 和套件執行工具：
- 安裝 Python 3.10 以上版本。
- 安裝 pipx 或 uv (uvx)，在獨立的 Python 環境中執行 MCP 伺服器。
在中啟用 Google Analytics API：
- 建立或選取專案。
- 在專案中啟用 Google Analytics Admin API (analyticsadmin.googleapis.com) 和 Google Analytics Data API (analyticsdata.googleapis.com)：
```
gcloud services enable analyticsadmin.googleapis.com \
  analyticsdata.googleapis.com \
  --project=YOUR_PROJECT_ID
```
授予 Google Analytics 資源存取權：
- 在 Google Analytics UI 中，為使用者帳戶或服務帳戶授予目標 Google Analytics 資源的「檢視者」角色 (roles/analytics.viewer) 以上權限。如需操作說明，請參閱「管理存取權和資料限制」。

設定驗證方法

Google Analytics MCP 伺服器會使用應用程式預設憑證 (ADC) 進行驗證，並搭配唯讀的 Google Analytics OAuth 2.0 範圍：

https://www.googleapis.com/auth/analytics.readonly

您可以使用 Google 使用者帳戶或服務帳戶設定 ADC。

選項 1：使用使用者憑證進行驗證

安裝並初始化 gcloud CLI。

執行 gcloud auth application-default login 並指定必要範圍：

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

如果您使用下載的 OAuth 2.0 桌面或網頁用戶端設定檔 (請參閱「管理 OAuth 用戶端」)，請傳遞 --client-id-file：

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file=YOUR_CLIENT_JSON_FILE

指令執行完畢後，請複製列印到控制台的憑證路徑 (Credentials saved to file: [PATH_TO_CREDENTIALS_JSON])。設定 MCP 用戶端時，您會在 GOOGLE_APPLICATION_CREDENTIALS 中使用這個路徑。

方法 2：使用服務帳戶進行驗證

如要使用具備 Google Analytics 資源檢視者權限的服務帳戶進行驗證，請按照下列步驟操作：

服務帳戶 JSON 金鑰檔案：在 MCP 用戶端設定中，將 GOOGLE_APPLICATION_CREDENTIALS 設為服務帳戶 JSON 檔案的絕對路徑。

服務帳戶模擬：使用 gcloud CLI 模擬服務帳戶，產生 ADC 憑證：

gcloud auth application-default login \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

設定 MCP 用戶端

伺服器會以 analytics-mcp 的形式發布在 PyPI 上，並公開 analytics-mcp 和 google-analytics-mcp 控制台指令碼。

在下列設定中，請替換：

將 PATH_TO_CREDENTIALS_JSON 替換為 ADC 或服務帳戶 JSON 檔案的絕對路徑。
YOUR_PROJECT_ID 替換為已啟用 Google Analytics API 的專案 ID。

Antigravity CLI 和 Antigravity IDE

安裝 Antigravity CLI 或 Antigravity IDE。

將 analytics-mcp 伺服器新增至 ~/.gemini/config/mcp_config.json (或工作區中的 .agents/mcp_config.json)：

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

確認 analytics-mcp 已連結：
- Antigravity CLI：執行 agy，然後輸入 /mcp，即可查看已設定的 MCP 伺服器。
- Antigravity IDE：依序開啟「Settings」 >「Customizations」 >「Installed MCP 伺服器」，然後點選「重新整理」。

Claude Desktop 和 Claude Code

如果是 Claude Desktop，請將伺服器新增至 claude_desktop_config.json 檔案 (macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json 或 Windows 上的 %APPDATA%\Claude\claude_desktop_config.json)：

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

如果是 Claude Code，請使用指令列工具註冊伺服器：

claude mcp add analytics-mcp \
  --scope user \
  -e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" \
  -e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \
  -- pipx run analytics-mcp

Cursor

在專案目錄中，將伺服器新增至 .cursor/mcp.json (或 ~/.cursor/mcp.json，用於全域設定)。您可以使用 uvx 或 pipx 叫用 google-analytics-mcp：

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "uvx",
      "args": ["--from", "analytics-mcp", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

如要使用 uvx 直接從 GitHub 執行最新的開發中版本，請更新 "args"：

"args": [
  "--from",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

或者，如要使用 pipx，請將 "command" 變更為 "pipx"，並將 "args" 設為：

"command": "pipx",
"args": [
  "run",
  "--spec",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

可用的 MCP 工具

Google Analytics MCP 伺服器會使用 Admin API 和 Data API v1，向 MCP 用戶端公開唯讀工具：

帳戶和資源探索 (Admin API)：
- get_account_summaries：列出已驗證使用者 (accountSummaries.list) 可存取的 Google Analytics 帳戶和資源。
- get_property_details：傳回特定 Google Analytics 資源 (properties.get) 的設定詳細資料。
- list_google_ads_links：列出資源 (properties.googleAdsLinks.list) 的 Google Ads 帳戶連結。
- list_property_annotations：列出為資源設定的備註 (properties.reportingDataAnnotations.list)。
報表和結構定義檢查 (Data API v1)：
- get_custom_dimensions_and_metrics：擷取為資源 (getMetadata) 定義的自訂維度和自訂指標。
- run_report：執行標準 Google Analytics 報表 (runReport)。
- run_realtime_report：執行 Google Analytics 即時報表 (runRealtimeReport)。
- run_funnel_report：執行 Google Analytics 漏斗探索報表 (runFunnelReport)。
- run_conversions_report：執行轉換成效報表 (runConversionsReport)。

提示範例

連線後，可以試著向 AI 助理提問，例如：

昨天有多少使用者？
昨天最暢銷的產品是哪些？
我的行銷預算為每月 $5,000 美元，需要提高收益。幫我建立以資料為依據的行銷計畫。
我的資源中設定了哪些自訂維度和自訂指標？
過去 90 天內，我的 Google Analytics 資源中最熱門的事件有哪些？

疑難排解

請參閱下列檢查清單，解決常見的設定和執行階段錯誤：

403 PERMISSION_DENIED (API 未啟用或資源權限不足)：
- 確認 GOOGLE_CLOUD_PROJECT 指定的專案已啟用 Google Analytics Admin API (analyticsadmin.googleapis.com) 和 Google Analytics Data API (analyticsdata.googleapis.com)。
- 確認驗證使用者或服務帳戶在 Google Analytics UI 中，至少具備目標 Google Analytics 資源的檢視者角色 (roles/analytics.viewer)。
- 如果錯誤訊息顯示 Request had insufficient authentication scopes，請使用 https://www.googleapis.com/auth/analytics.readonly 和 https://www.googleapis.com/auth/cloud-platform 範圍重新執行 gcloud auth application-default login。
缺少配額專案 (GOOGLE_CLOUD_PROJECT) 或 403 ACCESS_NOT_CONFIGURED：
- 使用使用者 ADC 憑證驗證的要求，必須有已啟用 Google Analytics API 的配額專案。在 MCP 伺服器的 env 設定中設定 "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"，或在 ADC 檔案中設定配額專案：
```
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
```
找不到 401 UNAUTHENTICATED 或憑證檔案：
- 請為 GOOGLE_APPLICATION_CREDENTIALS 使用絕對路徑 (例如 /Users/username/.config/gcloud/application_default_credentials.json)。請避免使用 ~ 或 $HOME 變數，因為許多 MCP 主機不會在 JSON 設定檔中展開殼層變數。
- 如果使用者憑證已過期，請重新執行 gcloud auth application-default login。
伺服器無法啟動 (spawn pipx ENOENT、uvx: command not found 或 Python 版本錯誤)：
- 確認已安裝 Python 3.10 以上版本 (python3 --version)。
- 桌面 GUI 應用程式 (例如 Claude Desktop 和 Cursor) 通常不會沿用互動式殼層 PATH。將 "command" 中的 "pipx" 或 "uvx" 替換為 which pipx 或 which uvx 傳回的絕對二進位檔路徑 (例如 /opt/homebrew/bin/pipx 或 /Users/username/.local/bin/pipx)。