Google Ads MCP

Google Ads MCP

一款将 Google Ads 与 Claude AI 连接起来的工具，让你能够通过自然语言对话分析广告数据。通过此集成，你可以获取广告系列信息、效果指标、关键词分析和广告管理功能——只需与 Claude 简单聊天即可。

---

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

1. 账户管理

   • 在一处查看所有 Google Ads 账户
   • 获取账户详情和基本广告系列信息

2. 广告系列分析与报告

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

3. 关键词与广告效果

   • 找出表现最佳和表现不佳的关键词
   • 分析广告文案的效果
   • 查看质量得分和竞争指标
   • 获取有关如何优化广告系列的可行建议

4. 预算与出价管理

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

---

Google Ads MCP 架构流程

flowchart TB
    User(User) -->|Interacts with| Claude
    Claude(Claude AI Assistant) -->|Makes requests to| MCP[Google Ads MCP Server]
    User -->|Can also use| Cursor[Cursor AI Code Editor]
    Cursor -->|Makes requests to| MCP
    
    subgraph "MCP Server"
        FastMCP[FastMCP Server] 
        Tools[Available Tools]
        Auth[Authentication]
        
        FastMCP -->|Exposes| Tools
        FastMCP -->|Uses| Auth
    end
    
    subgraph "Google Ads Tools"
        ListAccounts[list_accounts]
        ExecuteGAQL[execute_gaql_query]
        CampaignPerf[get_campaign_performance]
        AdPerf[get_ad_performance]
        RunGAQL[run_gaql]
    end
    
    Tools -->|Includes| ListAccounts
    Tools -->|Includes| ExecuteGAQL
    Tools -->|Includes| CampaignPerf
    Tools -->|Includes| AdPerf
    Tools -->|Includes| RunGAQL
    
    subgraph "Authentication"
        OAuth[OAuth 2.0 Client ID]
        ServiceAccount[Service Account]
        Credentials[Google Ads API Credentials]
        
        OAuth -->|Provides| Credentials
        ServiceAccount -->|Provides| Credentials
    end
    
    MCP -->|Communicates with| GoogleAdsAPI[Google Ads API]
    GoogleAdsAPI -->|Returns| AdData[Advertising Data]
    AdData -->|Analyzed by| Claude
    AdData -->|Visualized by| Claude
    AdData -->|Can be used by| Cursor
    
    Credentials -->|Authorizes| GoogleAdsAPI
    
    subgraph "Configuration"
        EnvVars[Environment Variables]
        ConfigFiles[Configuration Files]
        
        EnvVars -->|Configures| MCP
        ConfigFiles -->|Configures| Claude
        ConfigFiles -->|Configures| 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“列出工具”。

---

入门指南（无需编程经验！）

1. 设置 Google Ads API 访问权限

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

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

适用于个人用户或桌面应用：

1. 前往 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Google Ads API
4. 前往“Credentials”→“Create Credentials”→“OAuth Client ID”
5. 将应用类型选为“Desktop Application”
6. 下载 OAuth 客户端配置文件（client_secret.json）
7. 创建 Google Ads API 开发者令牌（见下文）

选项 B：服务账号（服务器到服务器身份验证）

更适合自动化系统或管理多个账号：

1. 前往 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Google Ads API
4. 前往“Credentials” → “Create Credentials” → “Service Account”
5. 下载服务账号密钥文件（JSON）
6. 授予服务账号访问 Google Ads 账号的权限
7. 创建 Google Ads API Developer token（见下文）

身份验证令牌刷新

应用现在包含完善的令牌刷新处理机制：

• OAuth 2.0 令牌：在可能的情况下，工具会自动刷新过期的 OAuth 令牌；如果刷新令牌无效，则会提示重新进行身份验证。
• 服务账号令牌：服务账号令牌会自动生成，并按需刷新，无需用户干预。

身份验证方式对比

以下情况请选择 OAuth 2.0 Client ID：

• 你正在构建桌面应用
• 用户需要明确授予访问权限
• 你要管理单个账号或少数几个个人账号
• 你希望用户能够控制访问权限

以下情况请选择服务账号：

• 你正在构建自动化系统
• 你需要服务器到服务器身份验证
• 你要通过编程方式管理多个账号
• 你不希望或不需要用户参与身份验证
• 你需要在无需用户干预的情况下自动刷新令牌

获取 Developer Token

1. 前往 https://ads.google.com 登录 Google Ads 账号
2. 点击顶部导航栏中的“Tools & Settings”（扳手图标）
3. 在“Setup”下，点击“API Center”
4. 如果尚未接受服务条款，请先接受
5. 点击“Apply for token”
6. 在申请表中填写你计划如何使用 API 的详细信息
7. 提交申请并等待审批（通常需要 1-3 个工作日）

注意：初始获得的 Developer Token 是测试令牌，存在一些限制。完成实现测试后，你可以申请生产令牌以解除这些限制。

了解 Login Customer ID

GOOGLE_ADS_LOGIN_CUSTOMER_ID 是可选项，主要用于以下情况：

• 你正在使用 Google Ads Manager Account（MCC）
• 你需要访问该管理账号下的多个客户账号

在以下情况下，Login Customer ID 应填写你的 Manager Account ID（格式：XXX-XXX-XXXX）：

• 你要访问管理账号下的多个账号
• 你希望使用管理账号凭据访问客户账号

以下情况可以跳过此设置：

• 你只访问单个 Google Ads 账号
• 你直接使用要访问的账号的凭据

查找 Manager Account ID：

1. 登录 Google Ads Manager Account
2. 点击设置图标（齿轮）
3. 页面会显示格式为 XXX-XXX-XXXX 的 Manager Account ID
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. 点击本页面顶部的绿色“Code”按钮
2. 选择“Download ZIP”
3. 将下载的文件解压到容易找到的位置（例如“文档”文件夹）

或者，如果你熟悉 Git：

git clone https://github.com/ixigo/mcp-google-ads.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 的配置文件中设置：

Claude Desktop

{
  "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_AUTH_TYPE": "oauth",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
      }
    }
  }
}

Cursor

{
  "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_AUTH_TYPE": "oauth",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
      }
    }
  }
}

6. 将 Claude 连接到 Google Ads

1. 如果尚未安装 Claude Desktop，请下载并安装
2. 确保已将 Google 服务账号凭据文件保存在电脑上的某个位置
3. 打开电脑上的终端（Mac）或命令提示符（Windows），并输入：

# For Mac users:
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# For Windows users:
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 Developer Token
• 添加 Google Ads Manager Account 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 Agent 可在需要时使用它。

在 Cursor 中使用 Google Ads MCP

在 Cursor 中工作时，你可以让 AI Agent 直接使用 Google Ads 工具。例如：

• “使用 Google Ads MCP 列出我的所有账户，并告诉我哪些账户的支出最高。”
• “你能使用 Google Ads MCP 分析我过去 30 天的广告系列表现吗？”
• “使用 Google Ads 工具运行 GAQL 查询，找出转化效果最好的关键词。”

Cursor 会提示你批准工具调用（除非你已启用 Yolo 模式），然后直接在聊天界面中显示结果。

Cursor 专属功能

在 Cursor 中使用 Google Ads MCP 时，你可以：

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	“显示账户 123-456-7890 过去 30 天表现最好的 10 个广告系列，标出 ROAS 低于 2 的广告系列，并提出优化策略。”
get_ad_performance	“全面分析我的搜索广告系列中哪些广告文案元素带来了最高的 CTR，并提供可执行的建议。”
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 别名（仅需设置一次）：

   # 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. 验证 Developer Token 是否有效且填写正确
4. 完成任何更改后，重启 Claude Desktop
5. 尝试使用工具时，查看 Claude 的回复中是否有错误消息
6. 手动运行服务时，确保已激活虚拟环境

Google Ads API 限制

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

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

其他意外问题

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

1. 复制你收到的完整错误消息
2. 联系 Ernesto Cohnen（邮箱：[email protected]）寻求支持，并提供以下信息：
   • 你尝试执行的操作
   • 完整的错误消息
   • 你的操作系统
   • 你已尝试过的步骤

你也可以咨询 AI 助手，它们通常可以通过针对具体情况提出解决方案，帮助诊断和解决技术问题。

请记住，大多数问题以前都有人遇到过，通常都有简单直接的解决方案。

测试你的设置

此代码库包含测试文件，可让你在将 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。

---

参与贡献

发现了 Bug 或有改进建议？欢迎提供反馈！在 GitHub 上提交 issue 或 pull request，或直接通过 [email protected] 联系 Ernesto Cohnen。

---

许可证

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

---

关于 ixigo

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

ixigo 是一家科技公司，致力于打造产品，帮助人们找到机票、火车票、巴士和酒店的优惠。我们是一群热爱旅行的人，致力于让每个人都能以更实惠的价格、更便捷地出行。