Google Ads MCP Server

🚀 Google Ads MCP Server

這是一個由FastMCP驅動的模型上下文協議（MCP）服務器，用於集成Google Ads API，並具備自動OAuth 2.0認證功能。它能將Google Ads API直接連接到Claude Desktop和其他MCP客戶端，支持無縫的OAuth 2.0認證、自動令牌刷新、GAQL查詢以及關鍵詞研究等功能。

🚀 快速開始

前提條件

在設置MCP服務器之前，您需要：

• 安裝Python 3.10或更高版本
• 擁有一個Google Cloud Platform賬戶
• 擁有一個具備API訪問權限的Google Ads賬戶

🔧 步驟1：Google Cloud Platform設置

1.1 創建Google Cloud項目

1. 訪問Google Cloud Console
2. 創建一個新項目：
   • 點擊“選擇項目”→“新建項目”
   • 輸入項目名稱（例如，“Google Ads MCP”）
   • 點擊“創建”

1.2 啟用Google Ads API

1. 在您的Google Cloud Console中：
   • 轉到“API和服務”→“庫”
   • 搜索“Google Ads API”
   • 點擊它並按下“啟用”

1.3 創建OAuth 2.0憑證

1. 轉到“API和服務”→“憑證”
2. 點擊“+ 創建憑證”→“OAuth 2.0客戶端ID”
3. 配置同意屏幕（如果是首次設置）：
   • 點擊“配置同意屏幕”
   • 選擇“外部”（除非您有Google Workspace）
   • 填寫必填字段：
     • 應用名稱：“Google Ads MCP”
     • 用戶支持電子郵件：您的電子郵件
     • 開發者聯繫信息：您的電子郵件
   • 依次點擊“保存並繼續”完成所有步驟
4. 創建OAuth客戶端：
   • 應用類型：“桌面應用程序”
   • 名稱：“Google Ads MCP客戶端”
   • 點擊“創建”
5. 下載憑證：
   • 點擊“下載JSON”按鈕
   • 將文件保存為client_secret_[長字符串].json到您的項目目錄中

🔧 步驟2：Google Ads API設置

2.1 獲取開發者令牌

1. 登錄到Google Ads
2. 轉到工具和設置（頂部導航欄中的扳手圖標）
3. 在“設置”下，點擊“API中心”
4. 如果提示，請接受服務條款
5. 點擊“申請令牌”
6. 填寫申請表：
   • 描述您的用例（例如，“用於廣告系列分析的MCP集成”）
   • 提供您的實現的技術細節
7. 提交併等待批准（通常需要1 - 3個工作日）

⚠️ 重要提示

您最初將獲得一個功能有限的測試令牌。測試完成後，您可以申請生產訪問權限。

2.2 查找您的開發者令牌

一旦獲得批准：

1. 返回Google Ads中的API中心
2. 複製您的開發者令牌（格式：XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX）

🔧 步驟3：安裝與設置

3.1 克隆並安裝

# 克隆倉庫
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# 創建虛擬環境（推薦）
python3 -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate

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

3.2 環境配置

在您的項目目錄中創建一個.env文件：

# 複製示例文件
cp .env.example .env

使用您的憑證編輯.env文件：

# 必需：Google Ads API開發者令牌
GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here

# 必需：OAuth憑證JSON文件的路徑（從Google Cloud下載）
GOOGLE_ADS_OAUTH_CONFIG_PATH=/full/path/to/your/client_secret_file.json

示例.env文件：

GOOGLE_ADS_DEVELOPER_TOKEN=ABCDEFG1234567890
GOOGLE_ADS_OAUTH_CONFIG_PATH=/Users/john/google-ads-mcp/client_secret_138737274875-abc123.apps.googleusercontent.com.json

🖥️ 步驟4：Claude Desktop集成

4.1 定位Claude配置文件

找到您的Claude Desktop配置文件：

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\Claude\claude_desktop_config.json

4.2 添加MCP服務器配置

編輯配置文件並添加您的Google Ads MCP服務器：

{
  "mcpServers": {
    "google-ads": {
      "command": "/full/path/to/your/project/.venv/bin/python",
      "args": [
        "/full/path/to/your/project/server.py"
      ]
    }
  }
}

實際示例：

{
  "mcpServers": {
    "google-ads": {
      "command": "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/.venv/bin/python",
      "args": [
        "/Users/marble-dev-01/workspace/google_ads_with_fastmcp/server.py"
      ]
    }
  }
}

⚠️ 重要提示

• 所有文件位置使用絕對路徑
• 在Windows上，路徑中使用正斜槓/或雙反斜槓\\
• 將your_developer_token_here替換為您的實際開發者令牌

4.3 重啟Claude Desktop

關閉並重新啟動Claude Desktop以加載新配置。

🔐 步驟5：首次認證

5.1 觸發OAuth流程

1. 打開Claude Desktop
2. 嘗試任何Google Ads命令，例如：

"列出我所有的Google Ads賬戶"

5.2 完成認證

1. 瀏覽器會自動打開到Google OAuth頁面
2. 使用您的Google賬戶登錄（具有Google Ads訪問權限的賬戶）
3. 點擊“允許”授予權限
4. 瀏覽器顯示成功頁面
5. 返回Claude - 您的命令將自動完成！

5.3 驗證設置

認證完成後，您應該看到：

• 項目目錄中創建了一個google_ads_token.json文件
• Claude的響應中列出了您的Google Ads賬戶

✨ 主要特性

• 🔐 自動OAuth 2.0 - 一次性瀏覽器認證，支持自動刷新
• 🔄 智能令牌管理 - 自動處理過期令牌
• 📊 GAQL查詢執行 - 運行任何Google Ads查詢語言查詢
• 🏢 賬戶管理 - 列出並管理Google Ads賬戶
• 🔍 關鍵詞研究 - 生成帶有搜索量數據的關鍵詞想法
• 🚀 FastMCP框架 - 基於現代MCP標準構建
• 🖥️ Claude Desktop就緒 - 與Claude Desktop直接集成
• 🛡️ 安全本地存儲 - 令牌本地存儲，永不暴露

📦 安裝指南

為了提供更簡單的設置體驗，我們提供了現成的安裝程序：

👉 下載安裝程序 - https://gomarble.ai/mcp

💻 使用示例

基礎賬戶操作

"列出我所有的Google Ads賬戶"

"顯示我的賬戶詳細信息以及哪些賬戶有活躍的廣告系列"

廣告系列分析

"顯示賬戶1234567890在過去30天內的廣告系列效果"

"獲取上週所有廣告系列的轉化數據"

"哪些廣告系列的每次轉化成本最高？"

關鍵詞研究

"使用賬戶1234567890為“數字營銷”生成關鍵詞想法"

"查找“AI自動化”的關鍵詞機會並提供搜索量數據"

"為頁面https://example.com/services研究關鍵詞"

自定義GAQL查詢

"為賬戶1234567890運行此GAQL查詢：
SELECT campaign.name, metrics.clicks, metrics.cost_micros 
FROM campaign 
WHERE segments.date DURING LAST_7_DAYS"

"獲取關鍵詞效果數據：
SELECT ad_group_criterion.keyword.text, metrics.ctr, metrics.average_cpc
FROM keyword_view 
WHERE metrics.impressions > 100"

高級GAQL示例

帶有收入的廣告系列效果

SELECT 
  campaign.id,
  campaign.name, 
  metrics.clicks, 
  metrics.impressions,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM campaign 
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC

關鍵詞效果分析

SELECT 
  campaign.name,
  ad_group_criterion.keyword.text, 
  ad_group_criterion.keyword.match_type,
  metrics.ctr,
  metrics.average_cpc,
  metrics.quality_score
FROM keyword_view 
WHERE segments.date DURING LAST_7_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.conversions DESC

設備效果細分

SELECT 
  campaign.name,
  segments.device,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'

📚 詳細文檔

📋 可用工具

工具	描述	參數	示例用法
list_accounts	列出所有可訪問的Google Ads賬戶	無	"列出我所有的Google Ads賬戶"
run_gaql	執行帶有自定義格式的GAQL查詢	customer_id, query, manager_id（可選）	"顯示賬戶1234567890的廣告系列效果"
run_keyword_planner	生成帶有指標的關鍵詞想法	customer_id, keywords, manager_id, page_url, 日期範圍選項	"為“數字營銷”生成關鍵詞想法"

⚠️ 重要提示

所有工具都會自動處理認證 - 無需提供令牌參數！

📁 項目結構

google-ads-mcp-server/
├── server.py                           # 主MCP服務器
├── oauth/
│   ├── __init__.py                     # 包初始化
│   └── google_auth.py                  # OAuth認證邏輯
├── google_ads_token.json               # 自動生成的令牌存儲（git忽略）
├── client_secret_[long-string].json    # 您的OAuth憑證（git忽略）
├── .env                                # 環境變量（git忽略）
├── .env.example                        # 環境模板
├── .gitignore                          # Git忽略文件
├── requirements.txt                    # Python依賴項
├── LICENSE                             # MIT許可證
└── README.md                           # 此文件

🔧 技術細節

安全與最佳實踐

文件安全

• ✅ 憑證文件被git忽略 - 永遠不會提交到版本控制中
• ✅ 本地令牌存儲 - 令牌存儲在本地的google_ads_token.json文件中
• ✅ 環境變量 - 敏感數據存儲在.env文件中
• ✅ 自動刷新 - 最小化令牌暴露時間

推薦的文件權限

# 為敏感文件設置安全權限
chmod 600 .env
chmod 600 google_ads_token.json
chmod 600 client_secret_*.json

生產環境考慮

1. 在生產環境中使用環境變量，而不是.env文件
2. 實施速率限制以遵守API配額
3. 在Google Cloud Console中監控API使用情況
4. 使用適當的訪問控制確保令牌存儲安全
5. 定期輪換令牌以增強安全性

故障排除

認證問題

問題	症狀	解決方案
未找到令牌	"正在啟動OAuth流程"消息	✅ 首次設置正常 - 完成瀏覽器認證
令牌刷新失敗	"刷新令牌失敗"錯誤	✅ 刪除google_ads_token.json並重新認證
OAuth流程失敗	瀏覽器錯誤或無響應	檢查憑證文件路徑和互聯網連接
權限被拒絕	瀏覽器中顯示"訪問被拒絕"	確保Google賬戶具有Google Ads訪問權限

配置問題

問題	症狀	解決方案
缺少環境變量	"環境變量未設置"	檢查.env文件和Claude配置的env部分
文件未找到	"FileNotFoundError"	驗證配置中的絕對路徑
模塊導入錯誤	"ModuleNotFoundError"	運行pip install -r requirements.txt
Python路徑問題	"命令未找到"	使用Python可執行文件的絕對路徑

Claude Desktop問題

問題	症狀	解決方案
服務器未連接	沒有可用的Google Ads工具	重啟Claude Desktop，檢查配置文件語法
無效的JSON配置	Claude啟動錯誤	驗證配置文件中的JSON語法
權限錯誤	啟動時顯示"權限被拒絕"	檢查文件權限和路徑

API問題

問題	症狀	解決方案
無效的客戶ID	"未找到客戶"	使用10位格式，不帶連字符：1234567890
API配額超出	"配額超出"錯誤	等待配額重置或請求增加
無效的開發者令牌	"認證失敗"	在Google Ads API中心驗證令牌
GAQL語法錯誤	"無效查詢"	檢查GAQL語法和字段名稱

調試模式

啟用詳細日誌記錄以進行故障排除：

# 在server.py中添加以進行調試
import logging
logging.basicConfig(level=logging.DEBUG)

獲取幫助

如果您遇到問題：

1. 仔細檢查錯誤消息 - 它通常會指出確切的問題
2. 驗證所有文件路徑是否為絕對路徑且正確
3. 確保環境變量已正確設置
4. 在Google Cloud Console中檢查API配額和計費情況
5. 任何配置更改後重啟Claude Desktop

🚀 高級配置

HTTP傳輸模式

對於Web部署或遠程訪問：

# 以HTTP模式啟動服務器
python3 server.py --http

Claude Desktop的HTTP配置：

{
  "mcpServers": {
    "google-ads": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

自定義令牌存儲

在oauth/google_auth.py中修改令牌存儲位置：

# 自定義令牌文件位置
def get_token_path():
    return "/custom/secure/path/google_ads_token.json"

管理器賬戶配置

用於管理MCC下的多個賬戶：

# 添加到.env文件
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

🤝 貢獻

我們歡迎貢獻！以下是開始的步驟：

開發設置

# 分叉並克隆倉庫
git clone https://github.com/yourusername/google-ads-mcp-server.git
cd google-ads-mcp-server

# 創建開發環境
python3 -m venv .venv
source .venv/bin/activate

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

# 設置開發環境
cp .env.example .env
# 將您的開發憑證添加到.env文件中

進行更改

1. 創建一個功能分支：git checkout -b feature/amazing-feature
2. 進行更改並編寫適當的測試
3. 使用不同的賬戶配置進行全面測試
4. 根據需要更新文檔
5. 提交更改：git commit -m '添加驚人的功能'
6. 推送到分支：git push origin feature/amazing-feature
7. 打開一個拉取請求並提供詳細描述

測試您的更改

# 測試認證流程
python3 server.py --test-auth

# 測試API連接性
python3 -c "
from oauth.google_auth import get_oauth_credentials
creds = get_oauth_credentials()
print('✅ 認證成功！')
"

# 使用Claude Desktop進行測試
# 將您的服務器添加到Claude配置中並測試各種命令

📊 API限制和配額

Google Ads API配額

• 基本訪問：每天15,000次操作
• 標準訪問：每天40,000次操作
• 請求速率：每個開發者令牌每分鐘1,600次請求

API使用的最佳實踐

1. 儘可能緩存結果以減少API調用
2. 使用日期範圍限制數據量
3. 支持時批量請求
4. 在Google Cloud Console中監控使用情況
5. 為速率限制錯誤實現重試邏輯

配額管理

# 在Google Cloud Console中監控使用情況
# 轉到API和服務 → 配額
# 搜索“Google Ads API”以查看當前使用情況

📄 許可證

本項目採用MIT許可證 - 有關詳細信息，請參閱LICENSE文件。

MIT許可證

Copyright (c) 2025 Google Ads MCP Server Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📈 路線圖

即將推出的功能

• 🔄 增強的關鍵詞研究，包含競爭對手分析
• 📊 內置數據可視化，帶有圖表和圖形
• 🤖 AI驅動的優化建議
• 📝 廣告系列創建和管理工具
• 🔍 高級報告功能
• 🌐 多語言支持

---

為MCP社區用心打造 ❤️

將您的Google Ads數據直接連接到AI助手，通過自然語言對話解鎖強大的廣告洞察。

加入我們的社區獲取幫助和更新

👉 Slack社區 - AI in Ads

也可以嘗試Facebook廣告MCP服務器

👉 Facebook Ads MCP - Facebook Ads MCP