Google Ads MCP

一个将 Google Ads 与 Claude AI 连接的工具，允许您通过自然语言对话分析您的广告数据。通过与 Claude 的简单聊天，您可以访问广告系列信息、效果指标、关键字分析和广告管理。

---

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

1. 账户管理

   • 在一个地方查看您的所有 Google Ads 账户
   • 获取账户详细信息和基本广告系列信息

2. 广告系列分析与报告

   • 发现哪些广告系列效果最佳
   • 跟踪展示次数、点击次数、转化次数和成本指标
   • 分析一段时间内的效果趋势
   • 比较不同的时间段以发现变化
   • 使用 Claude 创建的图表和图形可视化您的数据

3. 关键字和广告效果

   • 识别效果最佳和效果不佳的关键字
   • 分析广告文案效果
   • 检查质量得分和竞争指标
   • 获取有关如何改进广告系列的可操作见解

4. 预算与出价管理

   • 监控广告系列预算和支出
   • 分析出价策略和效果
   • 识别优化机会
   • 获取预算分配建议

---

Google Ads MCP 架构流程

flowchart TB
    User(用户) -->|与...交互| Claude
    Claude(Claude AI 助手) -->|向...发出请求| MCP[Google Ads MCP 服务器]
    User -->|也可以使用| Cursor[Cursor AI 代码编辑器]
    Cursor -->|向...发出请求| MCP
    
    subgraph "MCP 服务器"
        FastMCP[FastMCP 服务器] 
        Tools[可用工具]
        Auth[身份验证]
        
        FastMCP -->|公开| Tools
        FastMCP -->|使用| Auth
    end
    
    subgraph "Google Ads 工具"
        ListAccounts[list_accounts]
        ExecuteGAQL[execute_gaql_query]
        CampaignPerf[get_campaign_performance]
        AdPerf[get_ad_performance]
        RunGAQL[run_gaql]
    end
    
    Tools -->|包括| ListAccounts
    Tools -->|包括| ExecuteGAQL
    Tools -->|包括| CampaignPerf
    Tools -->|包括| AdPerf
    Tools -->|包括| RunGAQL
    
    subgraph "身份验证"
        OAuth[OAuth 2.0 客户端 ID]
        ServiceAccount[服务账户]
        Credentials[Google Ads API 凭据]
        
        OAuth -->|提供| Credentials
        ServiceAccount -->|提供| Credentials
    end
    
    MCP -->|与...通信| GoogleAdsAPI[Google Ads API]
    GoogleAdsAPI -->|返回| AdData[广告数据]
    AdData -->|由...分析| Claude
    AdData -->|由...可视化| Claude
    AdData -->|可以被...使用| Cursor
    
    Credentials -->|授权| GoogleAdsAPI
    
    subgraph "配置"
        EnvVars[环境变量]
        ConfigFiles[配置文件]
        
        EnvVars -->|配置| MCP
        ConfigFiles -->|配置| Claude
        ConfigFiles -->|配置| Cursor
    end

可用工具

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

您可以要求的内容	它做什么	您需要提供的内容
list_accounts	显示您的所有 Google Ads 账户	无需提供任何内容 - 只需提问！
execute_gaql_query	运行 Google Ads 查询语言查询	您的账户 ID 和 GAQL 查询
get_campaign_performance	显示包含效果数据的广告系列指标	您的账户 ID 和时间段
get_ad_performance	详细分析您的广告素材效果	您的账户 ID 和时间段
run_gaql	运行任何带有格式化选项的任意 GAQL 查询	您的账户 ID、查询和格式（表格、JSON 或 CSV）

使用高级查询工具

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

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

SELECT 
    campaign.name, 
    metrics.clicks, 
    metrics.impressions 
FROM campaign 
WHERE segments.date DURING LAST_7DAYS

示例 2：广告组效果

SELECT 
    ad_group.name, 
    metrics.conversions, 
    metrics.cost_micros 
FROM ad_group 
WHERE metrics.clicks > 100

示例 3：关键字分析

SELECT 
    keyword.text, 
    metrics.average_position, 
    metrics.ctr 
FROM keyword_view 
ORDER BY metrics.impressions DESC

有关所有可用工具及其详细说明的完整列表，请在设置后要求 Claude "list tools"。

---

入门（无需编码经验！）

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 客户端 ID：

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

如果符合以下条件，请选择服务账户：

• 您正在构建自动化系统
• 您需要服务器到服务器身份验证
• 您正在以编程方式管理多个账户
• 您不希望/不需要用户交互进行身份验证

1. 登录您的 Google Ads 账户：https://ads.google.com
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 - 您将与之聊天的 AI 助手

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

3. 下载 Google Ads MCP

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

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

或者，如果您熟悉 Git：

git clone https://github.com/ixigo/mcp-google-ads.git

4. 安装所需的组件

打开您计算机的终端 (Mac) 或命令提示符 (Windows)：

1. 导航到您解压缩文件的文件夹：

   # 示例（替换为您实际的路径）：
   cd ~/Documents/mcp-google-ads-main
   

2. 创建一个虚拟环境（这使项目依赖项隔离）：

   # 使用 uv（推荐）：
   uv venv .venv
   
   # 如果未安装 uv，请先安装它：
   pip install uv
   # 然后创建虚拟环境：
   uv venv .venv
   
   # 或者使用标准 Python：
   python -m venv .venv
   

   注意： 如果您在尝试安装 uv 时收到“pip not found”错误，请参阅下面的“如果您收到 'pip not found' 错误”部分。

3. 激活虚拟环境：

   # 在 Mac/Linux 上：
   source .venv/bin/activate
   
   # 在 Windows 上：
   .venv\Scripts\activate
   

4. 安装所需的依赖项：

   # 使用 uv：
   uv pip install -r requirements.txt
   
   # 或者使用标准 pip：
   pip install -r requirements.txt
   
   # 如果您遇到 MCP 包的任何问题，请单独安装它：
   pip install mcp
   

   如果您收到“pip not found”错误：

   # 首先确保 pip 已安装并更新：
   python3 -m ensurepip --upgrade
   python3 -m pip install --upgrade pip
   
   # 然后再次尝试安装 requirements：
   python3 -m pip install -r requirements.txt
   
   # 或者安装 uv：
   python3 -m pip install uv
   

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

5. 将 Claude 连接到 Google Ads

1. 如果您尚未下载并安装 Claude Desktop
2. 确保您的 Google 服务账户凭据文件保存在您计算机上的某个位置
3. 打开您计算机的终端 (Mac) 或命令提示符 (Windows) 并键入：

# 对于 Mac 用户：
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 对于 Windows 用户：
notepad %APPDATA%\Claude\claude_desktop_config.json

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

{
  "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"
      }
    }
  }
}

重要提示： 将所有路径和值替换为您账户的实际信息：

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

示例：

• Mac：
  • Python 路径：/Users/ernesto/Documents/mcp-google-ads/.venv/bin/python
  • 脚本路径：/Users/ernesto/Documents/mcp-google-ads/google_ads_server.py
• Windows：
  • 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 Desktop

6. 当 Claude 打开时，您现在应该在工具部分看到可用的 Google Ads 工具

5a. 连接到 Cursor (AI 代码编辑器)

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

设置 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 模式），然后直接在聊天界面中显示结果。

Cursor 特定功能

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

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

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

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

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

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

工具名称	示例提示
list_accounts	“列出我的所有 Google Ads 账户，并告诉我这个月哪些账户的支出最高。”
execute_gaql_query	“为账户 123-456-7890 执行此查询：SELECT campaign.name, metrics.clicks FROM campaign WHERE metrics.impressions > 1000”
get_campaign_performance	“显示过去 30 天内账户 123-456-7890 的前 10 个广告系列，突出显示 ROAS 低于 2 的任何广告系列，并提出优化策略。”
get_ad_performance	“对哪些广告文案元素在我的搜索广告系列中带来最佳点击率进行全面分析，并给我可操作的建议。”
run_gaql	“运行此查询并将其格式化为 CSV：SELECT ad_group.name, metrics.clicks, metrics.conversions FROM ad_group WHERE campaign.name LIKE '%Brand%'”

您还可以要求 Claude 组合多个工具并分析结果。 例如：

• “找到我转化率最高的前 20 个关键字，检查它们的质量得分和展示份额，并创建一个报告，突出显示扩展机会。”

• “分析我过去 90 天的账户效果趋势，确定我增长最快的广告系列，并检查是否有任何预算限制阻碍了它们。”

• “比较我的桌面与移动广告效果，使用图表可视化差异，并根据效果差距推荐需要移动出价调整的特定广告系列。”

• “确定我在搜索词上花费最多的广告系列，这些搜索词不在我的关键字列表中，然后建议将哪些搜索词添加为完全匹配关键字。”

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

---

数据可视化功能

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

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

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

---

故障排除

找不到 Python 命令

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

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

1. 创建一个 Python 别名（一次性设置）：

   # 对于 macOS 用户：
   sudo ln -s $(which python3) /usr/local/bin/python
   
   # 如果这不起作用，请尝试查找您的 Python 安装：
   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@ixigo.com 联系 Ernesto Cohnen 以获得支持，包括：
   • 您尝试做什么
   • 确切的错误消息
   • 您的操作系统
   • 您已经尝试过的任何步骤

您还可以咨询 AI 助手，它们通常可以通过为您的具体情况提出具体的解决方案来帮助诊断和解决技术问题。

请记住，大多数问题以前都遇到过，并且通常有可用的简单解决方案。

测试您的设置

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

设置测试文件

1. 确保您的虚拟环境已激活：

   # 在 Mac/Linux 上：
   source .venv/bin/activate
   
   # 在 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 查询

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

---

贡献

发现错误或有改进的想法？ 欢迎您的意见！ 在 GitHub 上打开一个问题或提交一个拉取请求，或者直接通过 ernesto@ixigo.com 联系 Ernesto Cohnen。

---

许可证

本项目根据 MIT 许可证获得许可。 有关详细信息，请参阅 LICENSE 文件。

---

关于 ixigo

ixigo 是印度领先的旅游应用程序，可帮助数百万旅客找到航班、火车、公共汽车和酒店的最佳优惠。 有关更多信息，请访问 ixigo.com。

<img src="ixigo-logo.png" alt="ixigo logo" width="200px" />

ixigo 是一家技术公司，致力于构建产品，以帮助人们找到航班、火车、公共汽车和酒店的最佳优惠。 我们是一支充满热情的旅游爱好者团队，致力于让每个人都能负担得起且更容易获得旅行。