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 控制台
2. 创建一个新项目或选择现有项目
3. 启用 Google Ads API
4. 转到“凭据”→“创建凭据”→“OAuth 客户端 ID”
5. 将应用类型选择为“桌面应用”
6. 下载 OAuth 客户端配置文件（client_secret.json）
7. 创建 Google Ads API 开发者令牌（见下文）

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

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

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

身份验证令牌刷新

该应用程序现已包含强大的令牌刷新机制：

• OAuth 2.0 令牌：当可能时，工具会自动刷新过期的 OAuth 令牌；如果刷新令牌无效，则会提示重新进行身份验证。
• 服务帐号令牌：服务帐号令牌会根据需要自动生成并刷新，无需用户干预。

身份验证方法对比

选择 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 未找到”的错误，请参阅下方的“如果出现‘pip 未找到’错误”部分。

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 未找到”错误：

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

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

5. 设置环境配置

Google Ads MCP 现在支持通过环境文件进行配置，以简化设置过程。

使用 .env 文件（推荐）

1. 将 .env.example 文件复制到项目目录下的 .env：

   cp .env.example .env
   

2. 使用你喜欢的文本编辑器编辑 .env 文件，填入实际的配置值：

   # 在 Mac 上：
   nano .env
   
   # 在 Windows 上：
   notepad .env
   

3. 在 .env 文件中设置以下值：

   # 认证类型：“oauth”或“service_account”
   GOOGLE_ADS_AUTH_TYPE=oauth
   
   # 凭证文件路径（OAuth 客户端密钥或服务账号密钥）
   GOOGLE_ADS_CREDENTIALS_PATH=/path/to/your/credentials.json
   
   # 您的 Google Ads 开发者令牌
   GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here
   
   # 可选：管理帐号 ID（如果适用）
   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），输入以下命令：

   # 对于 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 天的广告系列表现吗？”
• “运行 GAQL 查询，利用 Google Ads 工具找出我转化率最高的关键词。”

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	“展示账户 123-456-7890 过去 30 天内排名前 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 控制台中检查您的 Google Ads API 配额限制。
2. 确保您的开发者令牌具有适当的访问级别。
3. 验证您是否已为服务账号授予了正确的权限。

其他意外问题

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

1. 复制您收到的确切错误信息。
2. 联系 Ernesto Cohnen，邮箱地址为 ernesto@ixigo.com 寻求支持，提供以下信息：
   • 您当时正在尝试执行的操作
   • 确切的错误信息
   • 您的操作系统
   • 您已经尝试过的步骤

此外，您也可以咨询 AI 助手，它们通常能够帮助诊断并解决技术问题，为您提供针对您具体情况的解决方案。

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

测试您的设置

该仓库包含测试文件，可让您在将 Google Ads API 与 Claude 或 Cursor 集成之前，验证其连接是否正常工作。

测试基本功能

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 查询。

测试身份验证和令牌刷新

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

1. 确保已激活虚拟环境，并且 .env 文件已正确配置。

2. 运行令牌刷新测试：

   python test_token_refresh.py
   

3. 该测试将：

   • 验证是否可以从您配置的身份验证类型（OAuth 或服务账号）加载凭据。
   • 显示当前令牌的状态及过期时间。
   • 测试客户 ID 格式化函数。
   • 对于 OAuth 令牌，尝试刷新令牌并验证是否成功。

令牌刷新测试可以帮助您确认 OAuth 和服务账号凭据均已正确配置，然后再将服务器与 Claude 或 Cursor 集成使用。

如果所有测试均成功完成，则说明您的设置已正确配置，可以与 Claude 或 Cursor 一起使用了。

---

贡献

发现 bug 或有改进建议？我们非常欢迎您的参与！您可以在 GitHub 上提交问题或拉取请求，也可以直接联系 Ernesto Cohnen，邮箱地址为 ernesto@ixigo.com。

---

许可证

本项目采用 MIT 许可证授权。详细信息请参阅 LICENSE 文件。

---

关于 ixigo

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

ixigo 是一家科技公司，致力于开发帮助人们找到最优惠机票、火车票、巴士票和酒店预订的产品。我们是一支由旅行爱好者组成的团队，热衷于让旅行更加经济实惠、人人可及。

mcp-google-ads 快速上手指南

mcp-google-ads 是一个连接 Google Ads 与 Claude AI 的工具，允许你通过自然语言对话分析广告数据、查看活动表现、关键词分析及管理广告系列。

环境准备

在开始之前，请确保你的系统已安装以下软件：

• Python: 版本 3.11 或更高（推荐使用国内镜像源安装依赖）。
• Node.js: 用于运行 MCP 检查器及部分组件。
• Claude Desktop: 用于交互的 AI 助手客户端。
• Google Ads API 凭证: 需提前在 Google Cloud Console 和 Google Ads 后台获取（OAuth Client ID 或服务账号密钥，以及 Developer Token）。

提示：国内开发者在安装 Python 包时，建议使用清华或阿里镜像源加速下载。

安装步骤

1. 下载项目代码

你可以直接下载 ZIP 包解压，或使用 Git 克隆：

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

2. 创建并激活虚拟环境

推荐使用 uv 工具（速度快），也可以使用标准 venv。

使用 uv (推荐):

# 如果未安装 uv
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple

# 创建虚拟环境
uv venv .venv

# 激活环境 (Mac/Linux)
source .venv/bin/activate
# 激活环境 (Windows)
.venv\Scripts\activate

使用标准 Python:

python -m venv .venv
# 激活环境 (Mac/Linux)
source .venv/bin/activate
# 激活环境 (Windows)
.venv\Scripts\activate

3. 安装依赖

# 使用 uv 安装 (推荐，速度快)
uv pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或使用标准 pip
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 若遇到 MCP 包问题，可单独安装
pip install mcp -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 配置环境变量

复制示例配置文件并填入你的 Google Ads API 凭证信息：

cp .env.example .env

编辑 .env 文件，填入以下关键信息（根据你选择的认证方式填写）：

• GOOGLE_ADS_DEVELOPER_TOKEN: 你的开发者令牌。
• GOOGLE_ADS_CLIENT_ID / GOOGLE_ADS_CLIENT_SECRET: OAuth 客户端信息（若选 OAuth）。
• GOOGLE_ADS_SERVICE_ACCOUNT_KEY: 服务账号密钥文件路径或内容（若选服务账号）。
• GOOGLE_ADS_LOGIN_CUSTOMER_ID: (可选) 经理账号 (MCC) ID，格式为 XXX-XXX-XXXX。如果是单账户直连可留空。

基本使用

配置完成后，启动 Claude Desktop 并确保其加载了该 MCP 服务器。你可以在对话框中直接使用自然语言进行查询。

最简单的使用示例：

1. 查看所有账户 在 Claude 对话框中输入：

   "列出我所有的 Google Ads 账户" (对应工具：list_accounts)

2. 查询近期广告系列表现 输入：

   "显示过去 7 天我的广告系列点击量和展示次数" (对应工具：get_campaign_performance)

3. 执行自定义 GAQL 查询 如果你熟悉 SQL 风格的 GAQL 语法，可以直接让 Claude 运行复杂查询：

   "运行一个查询，找出过去 30 天转化率最高的前 5 个关键词，并按转化数降序排列"

   Claude 将自动调用 run_gaql 工具执行类似以下的逻辑：

   SELECT 
       keyword.text, 
       metrics.conversions 
   FROM keyword_view 
   WHERE segments.date DURING LAST_30_DAYS 
   ORDER BY metrics.conversions DESC 
   LIMIT 5
   

4. 数据可视化 你可以要求：

   "根据上周的数据，画一个展示各广告系列花费趋势的图表" Claude 将分析数据并生成可视化图表。