谷歌广告服务

Name: 谷歌广告服务
Author: cohnen

作者：cohnen324 星标更新：2025-10-17

安装使用来源：spider==github.com

项目介绍

Google Ads MCP

这是一个连接 Google Ads 和 Claude AI 的工具，允许您通过自然语言对话分析您的广告数据。此集成使您可以访问活动信息、性能指标、关键词分析以及广告管理——所有这些都可以通过与 Claude 的简单聊天来实现。

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

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

Google Ads MCP 架构流程

flowchart TB
    User(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 “列出工具”。

开始使用（无需编程经验）

1. 设置 Google Ads API 访问权限

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

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

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

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

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

适用于自动化系统或管理多个帐户：

转到 Google Cloud 控制台
创建新项目或选择现有项目
启用 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 Ads 经理帐户（MCC）
您需要访问经理帐户下的多个客户帐户

如果您正在访问经理帐户下的多个帐户，或者想要使用经理帐户凭据访问客户帐户，则登录客户ID应为您的经理帐户ID（格式：XXX-XXX-XXXX）。

如果您只需访问单个 Google Ads 帐户，或者直接使用要访问的帐户的凭据，则可以跳过此设置。

要找到您的经理帐户ID：

登录到您的 Google Ads 经理帐户
单击设置图标（齿轮）
您的经理帐户ID将以 XXX-XXX-XXXX 格式显示
下载凭据文件（一个 JSON 文件）

🎬 观看这个适合初学者的教程视频： 即将推出

2. 安装所需软件

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

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

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

3. 下载 Google Ads MCP

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

点击页面顶部的绿色“代码”按钮
选择“下载 ZIP”
将下载的文件解压到一个容易找到的位置（如您的文档文件夹）

如果您熟悉 Git：

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

4. 安装所需组件

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

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

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

创建虚拟环境（这将隔离项目的依赖项）：
```
# 使用 uv（推荐）：
uv venv .venv

# 如果未安装 uv，请先安装：
pip install uv
# 然后创建虚拟环境：
uv venv .venv

# 或使用标准 Python：
python -m venv .venv
```
注意： 如果尝试安装 uv 时遇到“pip 未找到”错误，请参阅下面的“如果遇到‘pip 未找到’错误”部分。

激活虚拟环境：

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

# 在 Windows 上：
.venv\Scripts\activate

安装所需依赖项：

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

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

使用您喜欢的文本编辑器编辑 .env 文件中的实际配置值：

# 使用您喜欢的文本编辑器编辑 .env 文件
# 在 Mac 上：
nano .env

# 在 Windows 上：
notepad .env

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

# 身份验证类型：“oauth”或“service_account”
GOOGLE_ADS_AUTH_TYPE=oauth

# 您的凭据文件路径（OAuth 客户端秘密或服务帐户密钥）
GOOGLE_ADS_CREDENTIALS_PATH=/path/to/your/credentials.json

# 您的 Google Ads 开发者令牌
GOOGLE_A_ADS_DEVELOPER_TOKEN=your_developer_token_here

# 可选：经理帐户ID（如有必要）
GOOGLE_ADS_LOGIN_CUSTOMER_ID=your_manager_account_id

保存文件。

应用程序启动时会自动从 .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

如果还没有，请下载并安装 Claude Desktop
确保您已经在计算机上的某个位置保存了 Google 服务帐户凭据文件
打开您的计算机的终端（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

保存文件：
- Mac：按 Ctrl+O，然后按 Enter，然后按 Ctrl+X 退出
- Windows：点击文件 > 保存，然后关闭记事本
重启 Claude Desktop
当 Claude 打开时，您应该在工具部分看到可用的 Google Ads 工具

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

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

设置 Cursor 集成

如果还没有，请下载并安装 Cursor
创建一个 Cursor MCP 配置文件：

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

对于全局配置（在所有项目中可用）： 在您的主目录中创建一个 `~/.cursor/mcp.json