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: https://github.com/google-marketing-solutions/google_ads_mcp
Google Ads MCP 開發者文件: https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server
Google Ads API Python Library: https://github.com/googleads/google-ads-python
ClawHub Skill Registry: https://clawhub.ai
google-ads-agent Skill: https://clawhub.ai/hanabi-jpn/google-ads-agent

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`