Google 广告 MCP

这款工具将Google Ads与 Claude AI 连接起来，让您能够通过自然语言对话分析广告数据。通过这项集成，您可以访问广告系列信息、效果指标、关键词分析和广告管理——所有这些都只需与 Claude 进行简单的聊天即可完成。

这个工具能为广告专业人士做什么？

1. 账户管理
   • 集中查看您的所有 Google Ads 帐号
   • 获取帐户详细信息和基本活动信息
2. 活动分析与报告
   • 发现哪些广告系列效果最佳
   • 跟踪展示次数、点击次数、转化次数和成本指标
   • 分析随时间推移的性能趋势
   • 比较不同的时间段来发现变化
   • 使用 Claude 创建的图表和图形来可视化您的数据
3. 关键词和广告效果
   • 确定表现最佳和表现不佳的关键词
   • 分析广告文案效果
   • 检查质量分数和竞争指标
   • 获取有关如何改进广告活动的可行见解
4. 预算和投标管理
   • 监控竞选预算和支出
   • 分析出价策略和效果
   • 确定优化机会
   • 获取预算分配建议

Google Ads MCP 架构流程

可用工具

设置此集成后，您可以要求 Claude 执行以下操作：

使用高级查询工具

run_gaql工具功能非常强大，因为它允许您运行任何自定义 Google 广告查询语言 (GAQL) 查询。以下是一些您可以使用的示例查询：

示例 1：基本广告系列指标

示例 2：广告组效果

示例3：关键字分析

要获得所有可用工具的完整列表及其详细描述，请在设置后要求 Claude“列出工具”。

入门（无需编码经验！）

1. 设置 Google Ads API 访问权限

在使用此工具之前，您需要创建 API 凭据，以允许 Claude 访问您的 Google Ads 数据。您可以选择以下两种身份验证方法：

选项 A：OAuth 2.0 客户端 ID（用户身份验证）

最适合个人用户或桌面应用程序：

1. 前往Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Google Ads API
4. 转到“凭证”→“创建凭证”→“OAuth 客户端 ID”
5. 选择“桌面应用程序”作为应用程序类型
6. 下载 OAuth 客户端配置文件（client_secret.json）
7. 创建 Google Ads API 开发者令牌（见下文）

选项 B：服务帐户（服务器到服务器身份验证）

更适合自动化系统或管理多个帐户：

1. 前往Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Google Ads API
4. 前往“凭证”→“创建凭证”→“服务帐户”
5. 下载服务帐号密钥文件 (JSON)
6. 授予服务帐号访问您的 Google Ads 帐号的权限
7. 创建 Google Ads API 开发者令牌（见下文）

身份验证令牌刷新

该应用程序现在包括强大的令牌刷新处理：

• OAuth 2.0 令牌：该工具将在可能时自动刷新过期的 OAuth 令牌，或者在刷新令牌无效时提示重新进行身份验证。
• 服务帐户令牌：服务帐户令牌根据需要自动生成和刷新，无需用户干预。

认证方法比较

如果出现以下情况，请选择 OAuth 2.0 客户端 ID：

• 您正在构建一个桌面应用程序
• 用户需要明确授予访问权限
• 您正在管理一个帐户或几个个人帐户
• 您希望用户能够控制访问权限

如果出现以下情况，请选择服务帐户：

• 您正在构建一个自动化系统
• 您需要服务器到服务器的身份验证
• 您正在以编程方式管理多个帐户
• 您不希望/不需要用户交互来进行身份验证
• 您需要自动刷新令牌而无需用户干预

获取开发者令牌

1. 访问https://ads.google.com登录您的 Google Ads 帐号
2. 单击顶部导航中的“工具和设置”（扳手图标）
3. 在“设置”下，点击“API 中心”
4. 如果您尚未接受服务条款，请接受
5. 点击“申请代币”
6. 填写申请表，详细说明您计划如何使用 API
7. 提交申请并等待批准（通常1-3个工作日）

注意：最初，您将获得一个测试版开发者令牌，该令牌有一些限制。测试完您的实现后，您可以申请一个可以移除这些限制的生产令牌。

了解登录客户 ID

GOOGLE_ADS_LOGIN_CUSTOMER_ID是可选的，主要用于：

• 您正在使用 Google Ads 经理帐户 (MCC)
• 您需要访问该经理帐号下的多个客户帐号

如果出现以下情况，则登录客户 ID 应为您的经理帐户 ID（格式：XXX-XXX-XXXX）：

• 您正在访问一个经理帐号下的多个帐号
• 您想使用经理帐号凭据访问客户帐号

如果出现以下情况，您可以跳过此设置：

• 您仅访问一个 Google Ads 帐户
• 您正在使用您想要访问的帐户的凭据

要查找您的经理帐户 ID，请执行以下操作：

1. 登录您的 Google Ads 经理帐户
2. 点击设置图标（齿轮）
3. 您的经理帐户 ID 将以 XXX-XXX-XXXX 格式显示
4. 下载凭证文件（JSON 文件）

**🎬 在 YouTube 上观看这个适合初学者的教程：**即将推出

2.安装所需软件

您需要在计算机上安装以下工具：

• Python （3.11 或更高版本）- 用于运行 Google Ads 和 Claude 之间的连接
• Node.js - 运行 MCP 检查器和某些 MCP 组件所需
• Claude Desktop - 与您聊天的人工智能助手

在继续之前，请确保 Python 和 Node.js 都已正确安装并在系统路径中可用。

3. 下载 Google Ads MCP

您需要将此工具下载到您的计算机上。最简单的方法是：

1. 单击此页面顶部的绿色“代码”按钮
2. 选择“下载 ZIP”
3. 将下载的文件解压到您可以轻松找到的位置（例如您的 Documents 文件夹）

或者，如果您熟悉 Git：

4.安装所需组件

打开计算机的终端（Mac）或命令提示符（Windows）：

1. 导航到解压缩文件的文件夹：
   # Example (replace with your actual path): cd ~/Documents/mcp-google-ads-main
2. 创建虚拟环境（这可以使项目依赖关系保持隔离）：
   # Using uv (recommended): uv venv .venv # If uv is not installed, install it first: pip install uv # Then create the virtual environment: uv venv .venv # OR using standard Python: python -m venv .venv
   **注意：**如果您在尝试安装 uv 时收到“pip not found”错误，请参阅下面的“如果收到‘pip not found’错误”部分。
3. 激活虚拟环境：
   # On Mac/Linux: source .venv/bin/activate # On Windows: .venv\Scripts\activate
4. 安装所需的依赖项：
   # Using uv: uv pip install -r requirements.txt # OR using standard pip: pip install -r requirements.txt # If you encounter any issues with the MCP package, install it separately: pip install mcp
   如果出现“pip not found”错误：
   # First ensure pip is installed and updated: python3 -m ensurepip --upgrade python3 -m pip install --upgrade pip # Then try installing the requirements again: python3 -m pip install -r requirements.txt # Or to install uv: python3 -m pip install uv

当您在命令提示符的开头看到(.venv)时，这表示虚拟环境处于活动状态，并且依赖项将安装在那里，而不会影响系统 Python 安装。

5.设置环境配置

Google Ads MCP 现在支持环境文件配置，以便于更轻松地进行设置。

使用 .env 文件（推荐）

1. 将.env.example文件复制到项目目录中的.env ：
   cp .env.example .env
2. 使用您的实际配置值编辑.env文件：
   # Edit the .env file with your favorite text editor # For Mac: nano .env # For Windows: notepad .env
3. 在.env文件中设置以下值：
   # Authentication Type: "oauth" or "service_account" GOOGLE_ADS_AUTH_TYPE=oauth # Path to your credentials file (OAuth client secret or service account key) GOOGLE_ADS_CREDENTIALS_PATH=/path/to/your/credentials.json # Your Google Ads Developer Token GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here # Optional: Manager Account ID (if applicable) GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id
4. 保存文件。

应用程序启动时将自动从.env文件加载这些值。

使用直接环境变量

您还可以直接在系统中或 Claude 或 Cursor 的配置文件中设置环境变量：

对于克劳德桌面

对于光标

6. 将 Claude 连接到 Google Ads

1. 如果您还没有下载并安装Claude Desktop
2. 确保您的 Google 服务帐户凭据文件已保存在计算机上的某个位置
3. 打开计算机的终端（Mac）或命令提示符（Windows）并输入：

添加以下文本（这告诉 Claude 如何连接到 Google Ads）：

**重要提示：**请使用您帐户的实际信息替换所有路径和值：

• 第一个路径应该指向虚拟环境中的 Python 可执行文件
• 第二条路径应指向您解压的文件夹中的google_ads_server.py文件
• 第三条路径应指向您的 Google 服务帐户凭据 JSON 文件
• 添加您的 Google Ads 开发者令牌
• 添加您的 Google Ads 管理器帐户 ID（如果适用）

例子：

• 苹果：
  • Python 路径： /Users/ernesto/Documents/mcp-google-ads/.venv/bin/python
  • 脚本路径： /Users/ernesto/Documents/mcp-google-ads/google_ads_server.py
• 视窗：
  • Python 路径： C:\\Users\\ernesto\\Documents\\mcp-google-ads\\.venv\\Scripts\\python.exe
  • 脚本路径： C:\\Users\\ernesto\\Documents\\mcp-google-ads\\google_ads_server.py

4. 保存文件：
   • Mac：按 Ctrl+O，然后按 Enter，然后按 Ctrl+X 退出
   • Windows：单击文件 > 保存，然后关闭记事本
5. 重启Claude桌面
6. 当 Claude 打开时，您应该会在工具部分看到可用的 Google Ads 工具

5a. 连接到光标（AI代码编辑器）

Cursor 是一款 AI 驱动的代码编辑器，可通过 MCP 工具进行增强。您可以将这款 Google Ads MCP 工具与 Cursor 集成，从而直接在您的编码环境中分析广告数据。

设置光标集成

1. 如果您还没有，请下载并安装Cursor
2. 创建 Cursor MCP 配置文件：**对于项目特定的配置：**在项目目录中创建一个.cursor/mcp.json文件。**对于全局配置（在所有项目中可用）：**在您的主目录中创建一个~/.cursor/mcp.json文件。
3. 将以下配置添加到您的 MCP 配置文件：
   { "mcpServers": { "googleAdsServer": { "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], "env": { "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json", "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" } } } }
   **重要提示：**将所有路径和值替换为您帐户的实际信息，就像在 Claude Desktop 配置中一样。
4. 重新启动 Cursor 或重新加载工作区以应用新配置。
5. Google Ads MCP 现在将出现在 Cursor 的“可用工具”部分，并可在需要时由 Cursor 的 AI 代理使用。

在 Cursor 中使用 Google Ads MCP

使用 Cursor 时，您可以要求 AI 代理直接使用 Google Ads 工具。例如：

• “使用 Google Ads MCP 列出我的所有帐户并显示哪些帐户的支出最高。”
• “您能否使用 Google Ads MCP 分析我过去 30 天的广告系列效果？”
• “使用 Google Ads 工具运行 GAQL 查询来查找转化率最高的关键字。”

Cursor 将提示您批准该工具的使用（除非您启用了 Yolo 模式），然后直接在聊天界面中显示结果。

游标特定功能

将 Google Ads MCP 与 Cursor 结合使用时，您可以：

1. 结合代码和广告分析：要求 Cursor 分析您的营销相关代码以及实际的广告活动效果数据。
2. 生成数据可视化：直接在您的开发环境中请求广告效果的图表和可视化。
3. 实施建议：让 Cursor 根据您的实际广告数据建议代码改进。

这种集成对于从事营销自动化、分析仪表板或电子商务应用程序的开发人员尤其有价值，因为广告效果直接影响代码决策。

6.开始分析您的广告数据！

现在，您可以向 Claude 询问有关 Google Ads 数据的问题！Claude 不仅可以检索数据，还可以分析数据、解释趋势并创建可视化图表，帮助您更好地了解广告效果。

以下是一些可以与每个工具一起使用的强大提示：

你也可以让 Claude 组合多种工具并分析结果。例如：

• “找到我的前 20 个转化关键字，检查它们的质量得分和展示份额，并创建一份报告，重点介绍扩展机会。”
• “分析我帐户过去 90 天的效果趋势，确定增长最快的广告系列，并检查是否有任何预算限制阻碍它们的发展。”
• “比较我的桌面广告和移动广告的效果，用图表直观地展示差异，并根据效果差距推荐需要调整移动出价的特定广告系列。”
• “确定我在关键字列表中未包含的搜索字词上花费最多的广告系列，然后建议将哪些搜索字词添加为完全匹配关键字。”

Claude 将使用 Google Ads 工具获取数据，以易于理解的格式呈现数据，在有用时创建可视化效果，并根据结果提供可行的见解。

数据可视化功能

Claude 可以帮助您以多种方式可视化您的 Google Ads 数据：

• 趋势图：查看指标随时间如何变化
• 比较图表：比较不同的广告系列或广告组
• 效果分布：了解您的广告在不同设备或受众群体中的表现
• 相关性分析：确定支出和转化指标之间的关系
• 热图：使用颜色编码表示来可视化复杂数据集

在分析数据时，只需要求 Claude“可视化”或“创建图表”，它就会生成适当的可视化效果，以帮助您更好地理解信息。

故障排除

未找到 Python 命令

在 macOS 上，默认的 Python 命令通常是python3而不是python ，这可能会导致包括 Node.js 集成在内的某些应用程序出现问题。

如果遇到与找不到 Python 相关的错误，可以创建别名：

1. 创建 Python 别名（一次性设置）：
   # For macOS users: sudo ln -s $(which python3) /usr/local/bin/python # If that doesn't work, try finding your Python installation: sudo ln -s /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 /usr/local/bin/python
2. 验证别名是否有效：
   python --version

这会创建一个符号链接，以便当应用程序调用python时，它们实际上会使用您的python3安装。

Claude配置问题

如果您在连接时遇到问题：

1. 确保配置中的所有文件路径都是正确的，并使用完整路径
2. 检查您的服务帐号是否有权访问您的 Google Ads 帐号
3. 验证您的开发者令牌是否有效且输入正确
4. 进行任何更改后重新启动 Claude Desktop
5. 尝试使用工具时，请查看 Claude 的回复中的错误消息
6. 确保手动运行服务器时虚拟环境已激活

Google Ads API 限制

如果您遇到与 API 配额或权限相关的问题：

1. 在 Google Cloud Console 中检查您的 Google Ads API 配额限制
2. 确保您的开发者令牌具有适当的访问级别
3. 验证您是否已向服务帐号授予适当的权限

其他意外问题

如果您在安装或使用过程中遇到任何其他意外问题：

1. 复制您收到的确切错误消息
2. 请联系 Ernesto Cohnen（邮箱： ernesto@ixigo.com）获取支持，包括：
   • 你想做什么
   • 确切的错误信息
   • 您的操作系统
   • 您已尝试过的任何步骤

您还可以咨询人工智能助手，它通常可以针对您的情况提出具体的解决方案来帮助诊断和解决技术问题。

请记住，大多数问题以前都已被其他人遇到过，并且通常都有一个简单的解决方案。

测试您的设置

该存储库包含测试文件，可让您在将 Google Ads API 连接与 Claude 或 Cursor 一起使用之前验证其是否正常工作。

测试基本功能

1. 确保您的虚拟环境已激活：
   # On Mac/Linux: source .venv/bin/activate # On Windows: .venv\Scripts\activate
2. 在测试文件中配置环境变量或在您的环境中设置它们：
   • 在文本编辑器中打开test_google_ads_mcp.py
   • 找到以if not os.environ.get("GOOGLE_ADS_CREDENTIALS_PATH"):
   • 使用您的实际凭据更新占位符值，或者如果您已将它们设置为环境变量，请注释掉此部分
3. 运行测试：
   python test_google_ads_mcp.py
4. 测试将：
   • 列出您的所有 Google Ads 帐号
   • 使用第一个帐户 ID 来测试广告系列效果检索
   • 测试广告效果数据
   • 检索广告创意
   • 运行示例 GAQL 查询

测试身份验证和令牌刷新

要专门测试身份验证和令牌刷新机制：

1. 确保您的虚拟环境已激活并且您的.env文件已配置。
2. 运行令牌刷新测试：
   python test_token_refresh.py
3. 本次测试将：
   • 验证是否可以从您配置的身份验证类型（OAuth 或服务帐户）加载凭据
   • 显示有关当前令牌状态和到期时间的信息
   • 测试客户ID格式化功能
   • 对于 OAuth 令牌，尝试刷新令牌并验证其是否有效

令牌刷新测试可以帮助确认在使用 Claude 或 Cursor 服务器之前 OAuth 和服务帐户凭据均已正确配置。

如果所有测试都成功完成，则您的设置运行正常，可以与 Claude 或 Cursor 一起使用。

贡献

发现了错误或有改进建议？欢迎您提出宝贵意见！请在 GitHub 上提交问题或拉取请求，或者直接联系 Ernesto Cohnen，邮箱地址为ernesto@ixigo.com 。

执照

本项目遵循 MIT 许可证。详情请参阅LICENSE文件。

关于ixigo

ixigo 是印度领先的旅行应用程序，帮助数百万旅行者找到最优惠的航班、火车、巴士和酒店。更多信息，请访问ixigo.com 。

ixigo 是一家科技公司，致力于开发各种产品，帮助人们找到最优惠的航班、火车、巴士和酒店。我们团队由一群热爱旅行的人组成，致力于让每个人都能以更实惠的价格享受旅行的便利。