Claude Code × Google Ads MCP 原生整合完整教學

Aiko · March 16, 2026, 12:38pm

Claude Code × Google Ads MCP 原生整合完整教學

本教學使用 Google 官方開源的 Google Ads MCP Server，不使用 Adspirer 或任何第三方代理方案。

1. 方案總覽與選擇

Google 官方目前提供兩個 MCP Server 方案（皆為原生、開源）：

方案 A：Google 官方 (google-marketing-solutions)【推薦】

GitHub: https://github.com/google-marketing-solutions/google_ads_mcp
優點: Google 團隊維護，使用 google-ads.yaml 標準認證，與 Google Ads Python Library 一致
工具: search（GAQL 查詢）、list_accessible_customers（列出帳戶）
狀態: 實驗性質，唯讀（read-only）
授權: Apache 2.0

方案 B：社群版 (cohnen/mcp-google-ads)

GitHub: https://github.com/cohnen/mcp-google-ads
優點: 支援更多工具（campaign performance、ad performance、keyword analytics）
狀態: 社群維護

本教學以方案 A（Google 官方）為主，方案 B 為輔。

2. 前置需求

在開始之前，請確認你已具備以下條件：

Python 3.12 或以上版本
pipx 或 uv（Python 套件執行工具）
一個 Google Ads 帳戶（或 MCC 管理帳戶）
一個 Google Cloud Project
Claude Code 已安裝並可正常運行

安裝 pipx（如尚未安裝）：

# macOS
brew install pipx
pipx ensurepath

# Linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# 或者使用 uv（更快速）
curl -LsSf https://astral.sh/uv/install.sh | sh

3. Google Cloud 設定（OAuth 2.0）

步驟 3.1：建立 Google Cloud Project

前往 Google Cloud Console
點擊上方的「選取專案」→「新增專案」
輸入專案名稱（例如：google-ads-mcp），點擊「建立」

步驟 3.2：啟用 Google Ads API

在 Google Cloud Console 中，前往「API 和服務」→「程式庫」
搜尋 Google Ads API
點擊「啟用」

步驟 3.3：建立 OAuth 2.0 憑證

前往「API 和服務」→「憑證」
點擊「建立憑證」→「OAuth 用戶端 ID」
如果尚未設定同意畫面，先完成「OAuth 同意畫面」設定：
- 選擇「外部」使用者類型
- 填寫應用程式名稱、使用者支援電子郵件
- 新增範圍（scope）：https://www.googleapis.com/auth/adwords
- 新增測試使用者（你自己的 Google 帳號）
回到建立 OAuth 用戶端 ID：
- 應用程式類型：選擇「桌面應用程式」
- 名稱：Google Ads MCP
點擊「建立」
下載 JSON 檔案，儲存為 client_secret.json

4. Google Ads Developer Token 取得

登入 Google Ads
點擊「工具與設定」（扳手圖示）→「設定」→「API 中心」
如果尚未申請，點擊「申請存取權」
複製你的 Developer Token（22 個字元的字串）

注意：新申請的 Developer Token 預設為「測試帳戶」等級，功能有限。通過驗證後可升級為正式存取。

5. 產生 google-ads.yaml 憑證檔

方法一：使用 Google 官方腳本自動產生

# 下載 Google Ads Python Library 的認證範例
pip install google-ads

# 執行認證流程
python -c "
from google_ads.client import GoogleAdsClient
# 或使用官方範例：
# https://github.com/googleads/google-ads-python/blob/main/examples/authentication/generate_user_credentials.py
"

你也可以直接下載並執行該腳本：

curl -O https://raw.githubusercontent.com/googleads/google-ads-python/main/examples/authentication/generate_user_credentials.py
python generate_user_credentials.py --client_id YOUR_CLIENT_ID --client_secret YOUR_CLIENT_SECRET

瀏覽器會開啟，登入你的 Google 帳戶並授權。完成後會得到 refresh_token。

方法二：手動建立 google-ads.yaml

在你的家目錄下建立 ~/google-ads.yaml：

# ~/google-ads.yaml
developer_token: "你的_DEVELOPER_TOKEN"
client_id: "你的_CLIENT_ID.apps.googleusercontent.com"
client_secret: "你的_CLIENT_SECRET"
refresh_token: "你的_REFRESH_TOKEN"
login_customer_id: "你的_MCC_帳戶_ID"  # 選填，但建議填寫（不含連字號）

重要：login_customer_id 是你的 MCC 管理帳戶 ID（如果有的話），格式為純數字，不含 - 連字號。

6. 在 Claude Code 中設定 MCP Server

方案 A：使用 Google 官方 MCP Server（推薦）

在 Claude Code 的終端機中，執行以下命令：

# 方法一：使用 claude mcp add 指令
claude mcp add google-ads \
  --command pipx \
  --args run --spec git+https://github.com/google-marketing-solutions/google_ads_mcp.git run-mcp-server \
  --env GOOGLE_ADS_CREDENTIALS=~/google-ads.yaml

或者，手動編輯 Claude Code 的 MCP 設定檔。設定檔位置根據作用範圍而異：

專案層級：.claude/mcp.json（在你的專案目錄下）
使用者層級：~/.claude/mcp.json

{
  "mcpServers": {
    "google-ads": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/google-marketing-solutions/google_ads_mcp.git",
        "run-mcp-server"
      ],
      "env": {
        "GOOGLE_ADS_CREDENTIALS": "/Users/你的使用者名稱/google-ads.yaml"
      },
      "timeout": 30000
    }
  }
}

方案 B：使用社群版 MCP Server

如果你需要更多功能（如 campaign performance 直接查詢）：

# 1. Clone 專案
git clone https://github.com/cohnen/mcp-google-ads.git ~/mcp-google-ads
cd ~/mcp-google-ads

# 2. 建立虛擬環境
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# 3. 安裝依賴
pip install -r requirements.txt

# 4. 設定環境變數（建立 .env 檔案）
cp .env.example .env
# 編輯 .env 填入你的認證資訊

Claude Code MCP 設定：

{
  "mcpServers": {
    "google-ads": {
      "command": "/Users/你的路徑/mcp-google-ads/.venv/bin/python",
      "args": [
        "/Users/你的路徑/mcp-google-ads/google_ads_server.py"
      ],
      "env": {
        "GOOGLE_ADS_AUTH_TYPE": "oauth",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/Users/你的路徑/mcp-google-ads/credentials.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "你的_DEVELOPER_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "你的_MCC_帳戶_ID"
      }
    }
  }
}

7. 驗證連接

設定完成後，重新啟動 Claude Code，然後執行：

# 在 Claude Code 中輸入
/mcp

你應該會看到 google-ads 伺服器列在結果中。然後嘗試以下對話：

列出我所有可存取的 Google Ads 客戶帳戶

如果成功，Claude 會回傳你帳戶下的所有客戶 ID 和帳戶名稱。

8. ClawHub 推薦 Skill

根據 ClawHub（clawhub.ai）上與 Google Ads 相關的熱門 Skill，以下是最推薦的選擇：

首推：`google-ads-agent`

來源: https://clawhub.ai/hanabi-jpn/google-ads-agent
說明: 一個 AI 驅動的 Google Ads 管理助手，支援 GAQL 查詢自動建構、多帳戶（MCC）架構、自動出價優化、品質分數修復、帳戶健康稽核、異常偵測、主管級報表
安裝:

npx clawhub@latest install google-ads-agent

備選：`google-ads-api`（by byungkyu）

來源: https://clawhub.ai/byungkyu/google-ads-api
說明: 透過 Managed OAuth 整合 Google Ads API，使用 GAQL 查詢 campaigns、ad groups、keywords 與成效指標
特色: 自帶 OAuth 管理，不需自行處理 token

備選：`claude-ads`

來源: https://github.com/AgriciDaniel/claude-ads
說明: 186 項跨平台廣告稽核項目，涵蓋 Google、Meta、YouTube、LinkedIn、TikTok 及 Microsoft Ads
安裝:

git clone https://github.com/AgriciDaniel/claude-ads.git
cd claude-ads
./install.sh

安全提醒：安裝任何 ClawHub Skill 前，請務必先檢閱 SKILL.md 的內容，確認沒有可疑的指令或下載行為。ClawHub 生態系曾被發現有惡意 Skill，請謹慎使用。

9. 可直接使用的 Claude Code Prompt

以下是你可以直接複製貼上到 Claude Code 中使用的 prompt：

Prompt 1：完整設定 Google Ads MCP Server

請幫我完成以下任務：

1. 確認我的環境是否已安裝 Python 3.12+ 和 pipx
2. 如果沒有 pipx，請幫我安裝
3. 檢查 ~/google-ads.yaml 是否存在，如果不存在請引導我建立
4. 使用以下指令將 Google 官方 MCP Server 加入 Claude Code：

claude mcp add google-ads \
  --command pipx \
  --args run --spec git+https://github.com/google-marketing-solutions/google_ads_mcp.git run-mcp-server \
  --env GOOGLE_ADS_CREDENTIALS=$HOME/google-ads.yaml

5. 驗證 MCP 連接是否成功（使用 /mcp 指令確認）
6. 嘗試呼叫 list_accessible_customers 工具來測試連接

如果任何步驟失敗，請顯示錯誤訊息並建議修復方法。

Prompt 2：設定完成後的 Google Ads 資料分析

你現在已經透過 MCP 連接到我的 Google Ads 帳戶。請執行以下操作：

1. 先呼叫 list_accessible_customers 列出所有帳戶
2. 針對主帳戶，使用 GAQL 查詢過去 30 天的所有活躍廣告活動：
   SELECT campaign.id, campaign.name, campaign.status, 
          metrics.impressions, metrics.clicks, metrics.ctr, 
          metrics.average_cpc, metrics.cost_micros, metrics.conversions
   FROM campaign
   WHERE campaign.status = 'ENABLED'
     AND segments.date DURING LAST_30_DAYS
   ORDER BY metrics.cost_micros DESC
3. 將結果整理成表格，並標示 CTR 低於 2% 或 CPC 高於平均值的異常項目
4. 根據數據給出 3-5 個優化建議

Prompt 3：一鍵安裝 + 稽核（整合 ClawHub Skill）

請依序執行以下步驟：

【第一步：環境檢查】
- 確認 python3 --version >= 3.12
- 確認 pipx 或 uv 已安裝
- 確認 ~/google-ads.yaml 存在且格式正確

【第二步：安裝 Google Ads MCP】
- 執行：claude mcp add google-ads --command pipx --args run --spec git+https://github.com/google-marketing-solutions/google_ads_mcp.git run-mcp-server --env GOOGLE_ADS_CREDENTIALS=$HOME/google-ads.yaml

【第三步：安裝 ClawHub google-ads-agent Skill（選配）】
- 執行：npx clawhub@latest install google-ads-agent

【第四步：驗證連接】
- 呼叫 list_accessible_customers 確認帳戶可存取
- 執行一個簡單的 GAQL 查詢測試

【第五步：快速稽核】
- 查詢過去 7 天 spend > 0 但 conversions = 0 的 campaigns
- 查詢 CTR 低於 1% 的 ad groups
- 彙整成「帳戶健康報告」

每個步驟完成後請回報狀態，如遇錯誤請直接嘗試修復。

10. 常見問題

Q: 出現 “Developer token is not approved” 錯誤？

你的 Developer Token 可能還在測試模式。測試模式只能存取測試帳戶。請前往 Google Ads API Center 申請正式存取權限。

Q: refresh_token 過期怎麼辦？

重新執行 generate_user_credentials.py 腳本取得新的 refresh_token，更新 google-ads.yaml。

Q: 可以寫入（修改廣告活動、調整出價）嗎？

Google 官方 MCP Server 目前為唯讀（read-only），無法修改廣告活動設定。如需寫入功能，請使用社群版方案或等待官方後續更新。

Q: Claude Code 找不到 MCP Server？

確認已重新啟動 Claude Code，並使用 /mcp 指令檢查。如果仍不顯示，請確認設定檔路徑是否正確。

Q: pipx 執行失敗？

嘗試改用 uv：

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "git+https://github.com/google-marketing-solutions/google_ads_mcp.git",
        "run-mcp-server"
      ],
      "env": {
        "GOOGLE_ADS_CREDENTIALS": "/path/to/google-ads.yaml"
      }
    }
  }
}

參考連結

Google 官方 MCP Server: GitHub - google-marketing-solutions/google_ads_mcp: The Google Ads MCP Server is an implementation of the Model Context Protocol (MCP) that enables Large Language Models (LLMs), such as Gemini, to interact directly with the Google Ads API. · GitHub
Google Ads MCP 開發者文件: Google Ads MCP server: Developer integration guide | Google Ads API | Google for Developers
Google Ads API Python Library: GitHub - googleads/google-ads-python: Google Ads API Client Library for Python · GitHub
ClawHub Skill Registry: https://clawhub.ai
google-ads-agent Skill: google-ads-agent — ClawHub

Claude Code × Google Ads MCP 原生整合完整教學

Claude Code × Google Ads MCP 原生整合完整教學

目錄

1. 方案總覽與選擇

方案 A：Google 官方 (google-marketing-solutions)【推薦】

方案 B：社群版 (cohnen/mcp-google-ads)

2. 前置需求

3. Google Cloud 設定（OAuth 2.0）

步驟 3.1：建立 Google Cloud Project

步驟 3.2：啟用 Google Ads API

步驟 3.3：建立 OAuth 2.0 憑證

4. Google Ads Developer Token 取得

5. 產生 google-ads.yaml 憑證檔

方法一：使用 Google 官方腳本自動產生

方法二：手動建立 google-ads.yaml

6. 在 Claude Code 中設定 MCP Server

方案 A：使用 Google 官方 MCP Server（推薦）

方案 B：使用社群版 MCP Server

7. 驗證連接

8. ClawHub 推薦 Skill

首推：google-ads-agent

備選：google-ads-api（by byungkyu）

備選：claude-ads

9. 可直接使用的 Claude Code Prompt

Prompt 1：完整設定 Google Ads MCP Server

Prompt 2：設定完成後的 Google Ads 資料分析

Prompt 3：一鍵安裝 + 稽核（整合 ClawHub Skill）

10. 常見問題

Q: 出現 “Developer token is not approved” 錯誤？

Q: refresh_token 過期怎麼辦？

Q: 可以寫入（修改廣告活動、調整出價）嗎？

Q: Claude Code 找不到 MCP Server？

Q: pipx 執行失敗？

參考連結

首推：`google-ads-agent`

備選：`google-ads-api`（by byungkyu）

備選：`claude-ads`