Name: Google Ads数据分析工具
Author: cohnen

使用说明

谷歌广告MCP

连接的工具谷歌广告借助Claude AI，您可以通过自然语言对话分析广告数据。通过这种集成，您可以访问活动信息、绩效指标、关键字分析和广告管理，所有这些都可以通过与Claude的简单聊天来实现。

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

账户管理
- 在一个地方查看您的所有Google Ads帐户
- 获取帐户详细信息和基本活动信息
活动分析和报告
- 发现哪些活动表现最佳
- 跟踪展示、点击、转化和成本指标
- 分析随时间变化的性能趋势
- 比较不同的时间段以发现变化
- 可视化您的数据 由Claude创建的图表
关键字和广告性能
- 识别表现最佳和不佳的关键字
- 分析广告文案效果
- 检查质量分数和竞争指标
- 获取关于如何改进您的广告系列的可操作见解
预算与投标管理
- 监控活动预算和支出
- 分析投标策略和绩效
- 识别优化机会
- 获取预算分配建议

谷歌广告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 该工具特别强大，因为它允许您运行任何自定义的谷歌广告查询语言（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:Auth2.0客户端ID（用户身份验证）

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

去 Google 云控制台
创建新项目或选择现有项目
启用Google Ads API
转到“凭据”→ “创建凭据”→ “OAuth客户端ID”
选择“桌面应用程序”作为应用程序类型
下载OAuth客户端配置文件（client_secret.json）
创建Google Ads API开发者代币（见下文）

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

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

去 Google 云控制台
创建新项目或选择现有项目
启用Google Ads API
转到“凭据”→ “创建凭据”→ “服务帐户”
下载服务帐户密钥文件（JSON）
授予服务帐户访问您的Google Ads帐户的权限
创建Google Ads API开发者代币（见下文）

身份验证令牌刷新

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

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

身份验证方法比较

在以下情况下选择OAuth 2.0客户端ID：

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

在以下情况下选择服务帐户：

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

获取开发者代币

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

注意：最初，您将获得一个有一些限制的测试开发人员令牌。一旦你测试了你的实现，你就可以申请一个消除这些限制的生产令牌。

了解登录客户ID

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

您正在使用Google广告管理器帐户（MCC）
您需要访问该经理帐户下的多个客户端帐户

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

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

在以下情况下，您可以跳过此设置：

您只能访问一个Google Ads帐户
您正在使用直接来自要访问的帐户的凭据

要查找您的经理帐户ID：

登录您的Google广告管理器帐户
点击设置图标（齿轮）
您的经理帐户ID将以XXX-XXX-XXXX格式显示
下载凭据文件（JSON文件）

🎬 在Youtube上观看此初学者友好教程： 即将推出

2.安装所需软件

您需要在计算机上安装这些工具：

python （3.11或更高版本）-这将运行Google Ads和Claude之间的连接
Node.js -运行MCP检查器和某些MCP组件所需
Claude桌面版 -您将与之聊天的AI助手

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

3.下载谷歌广告MCP

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

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

或者，如果你熟悉Git：

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

4.安装所需组件

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

导航到解压缩文件的文件夹：

# Example (replace with your actual path):
cd ~/Documents/mcp-google-ads-main

创建虚拟环境（这将使项目依赖关系保持隔离）：

# 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”错误，请参阅下面的“If you get'pip not found'error”部分。

激活虚拟环境：

# On Mac/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

安装所需的依赖项：

# 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文件（推荐）

复制 .env.example 文件到 .env 在您的项目目录中：
```
cp .env.example .env
```

编辑 .env 文件中包含您的实际配置值：

# Edit the .env file with your favorite text editor
# For Mac:
nano .env

# For Windows:
notepad .env

在您的 .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

保存文件。

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

使用直接环境变量

您还可以直接在系统中或Claude或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"
      }
    }
  }
}

对于光标

{
  "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服务帐户凭据文件保存在计算机上的某个位置
打开计算机的终端（Mac）或命令提示符（Windows），然后键入：

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

# For Windows users:
notepad %APPDATA%\Claude\claude_desktop_config.json

添加以下文本（这篇文章告诉克劳德如何连接到谷歌广告）：

{
  "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广告管理器帐户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

保存文件：
- Mac：按Ctrl+O，然后按Enter，再按Ctrl+X退出
- Windows：单击“文件”>“保存”，然后关闭记事本
重新启动克劳德桌面
当Claude打开时，您现在应该在工具部分看到可用的Google Ads工具

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

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

设置游标集成

如果还没有，请下载并安装光标
创建游标MCP配置文件：

对于项目特定配置： 创建一个 .cursor/mcp.json 项目目录中的文件。

对于全局配置（适用于所有项目）： 创建一个 ~/.cursor/mcp.json 将文件放在主目录中。

将以下配置添加到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配置中一样。

重新启动Cursor或重新加载工作区以应用新配置。
Google Ads MCP现在将出现在Cursor的“可用工具”部分，并可在需要时由Cursor人工智能代理使用。

在游标中使用谷歌广告MCP

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

“使用Google Ads MCP列出我的所有帐户，并向我显示哪些帐户的支出最高。”
“你能使用谷歌广告MCP分析我过去30天的广告活动表现吗？”
“使用Google Ads工具运行GAQL查询以查找我的热门转换关键字。”

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

光标特定功能

使用带有光标的Google Ads MCP时，您可以：

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

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

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

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

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

工具名称	示例提示
`list_accounts`	“列出我所有的谷歌广告账户，告诉我哪些账户本月的支出最高。”
`execute_gaql_query`	对帐户123-456-7890执行此查询：选择活动名称、度量值。从度量值大于1000的活动中单击
`get_campaign_performance`	“向我展示过去30天内帐户123-456-7890的前10个活动，突出显示ROAS低于2的任何活动，并建议优化策略。”
`get_ad_performance`	“全面分析哪些广告文案元素在我的搜索活动中推动了最佳点击率，并给我提供可行的建议。”
`run_gaql`	运行此查询并将其格式化为CSV格式：选择ad_group.name、metrics.clicks、metrics.convolutions FROM ad_group WHERE campaign.name，类似于“%Brand%”

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

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

克劳德将使用谷歌广告工具获取数据，以易于理解的格式呈现，在有帮助的情况下创建可视化，并根据结果提供可操作的见解。

数据可视化

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

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

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

故障排除

未找到Python命令

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

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

创建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

验证别名是否有效：
```
python --version
```

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

Claude配置问题

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

确保配置中的所有文件路径都正确，并使用完整路径
检查您的服务帐户是否可以访问您的Google Ads帐户
验证您的开发人员令牌是否有效且输入正确
进行任何更改后重新启动Claude Desktop
尝试使用工具时，在Claude的响应中查找错误消息
手动运行服务器时，确保您的虚拟环境已激活

Google Ads API限制

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

在Google云控制台中检查您的Google Ads API配额限制
确保您的开发者令牌具有适当的访问级别
验证您是否已授予服务帐户适当的权限

其他意外问题

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

复制您收到的确切错误消息
联系Ernesto Cohnenernesto@ixigo.com支持，包括：
- 你想做什么
- 确切的错误信息
- 您的操作系统
- 你已经尝试过的任何步骤

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

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

测试您的设置

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

测试基本功能

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

# On Mac/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

在测试文件中配置环境变量或在您的环境中设置它们：
- 打开 test_google_ads_mcp.py 在文本编辑器中
- 找到以开头的部分 if not os.environ.get("GOOGLE_ADS_CREDENTIALS_PATH"):
- 用您的实际凭据更新占位符值，或者如果您已将其设置为环境变量，请注释掉本节
运行测试：
```
python test_google_ads_mcp.py
```
测试将：
- 列出您的所有Google Ads帐户
- 使用第一个帐户ID测试活动性能检索
- 测试广告性能数据
- 检索广告创意
- 运行示例GAQL查询

测试身份验证和令牌刷新

要具体测试身份验证和令牌刷新机制：

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

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

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

贡献

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

许可证

该项目根据MIT许可证获得许可。请参阅许可证文件以获取详细信息。

关于ixigo

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

ixigo是一家技术公司，其产品旨在帮助人们找到航班、火车、公共汽车和酒店的最佳交易。我们是一个由旅行爱好者组成的团队，他们热衷于让每个人都能负担得起旅行。