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