使用说明

项目简介

Google Ads MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在连接 Claude AI 等 LLM 客户端与 Google Ads API。它允许用户通过自然语言与 Claude 交互，分析和管理 Google Ads 广告数据，为广告专业人士提供便捷的数据分析和决策支持。

主要功能点

账户管理: 查看和管理您的 Google Ads 账户，获取账户和基本广告系列信息。
广告系列分析与报告: 分析广告系列效果，跟踪关键指标（展示次数、点击次数、转化次数等），并支持 Claude 生成数据可视化图表。
关键词与广告效果分析: 识别表现优异和欠佳的关键词，分析广告文案效果，获取优化建议。
预算与出价管理: 监控广告系列预算和花费，分析出价策略效果，发现优化机会。
自定义 GAQL 查询: 支持执行 Google Ads Query Language (GAQL) 查询，灵活获取所需数据。
图片素材分析: 获取和分析广告账户中的图片素材，包括素材使用情况和效果数据。

安装步骤

安装必备软件: 确保已安装 Python 3.11+ 和 Node.js。
下载仓库代码: 从 GitHub 仓库页面下载 ZIP 文件并解压到本地，或使用 Git 克隆仓库。

创建并激活虚拟环境: 在解压后的仓库目录下，打开终端或命令提示符，创建 Python 虚拟环境并激活。

# 创建虚拟环境 (推荐使用 uv, 没有uv请先安装 pip install uv)
uv venv .venv
# 激活虚拟环境 (macOS/Linux)
source .venv/bin/activate
# 激活虚拟环境 (Windows)
.venv\Scripts\activate

安装 Python 依赖: 在虚拟环境中，安装项目所需的 Python 依赖包。

# 使用 uv 安装依赖
uv pip install -r requirements.txt
# 或者使用 pip 安装依赖
pip install -r requirements.txt

配置 Google Ads API 访问权限: 按照 README.md 文档指引，设置 Google Ads API 访问权限，获取 OAuth 2.0 客户端 ID 或服务账户密钥文件，并获取 Google Ads API 开发者令牌。
配置 MCP 服务器环境变量: 设置以下环境变量，用于 Google Ads API 认证：
- 'GOOGLE_ADS_CREDENTIALS_PATH': Google 服务账户密钥 JSON 文件或 OAuth 客户端凭据 JSON 文件的路径。
- 'GOOGLE_ADS_DEVELOPER_TOKEN': 您的 Google Ads API 开发者令牌。
- 'GOOGLE_ADS_LOGIN_CUSTOMER_ID' (可选): 如果您使用 Google Ads Manager Account (MCC)，请设置您的 Manager Account ID。
- 您也可以选择不使用环境变量，将配置信息直接写入 'claude_desktop_config.json' 或 '.cursor/mcp.json' 文件中。

服务器配置

MCP 服务器配置信息（JSON 格式），用于配置 Claude Desktop 或 Cursor 等 MCP 客户端：

{
  "mcpServers": {
    "googleAdsServer": {  // 服务器名称，可自定义
      "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python", // Python 解释器路径 (虚拟环境中的 python)
      "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"], // MCP 服务器脚本路径
      "env": {  // 环境变量 (可选，如果环境变量已在系统或终端中设置，则此处可以省略)
        "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json", // Google 服务账户密钥文件路径
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE", // Google Ads 开发者令牌
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE" // Google Ads 管理员账户 ID (可选)
      }
    }
  }
}

注意:

请将 '/FULL/PATH/TO/mcp-google-ads-main' 替换为您的 'mcp-google-ads' 仓库在您电脑上的实际路径。
请将 '/FULL/PATH/TO/mcp-google-ads-main/service_account_credentials.json' 替换为您的 Google 服务账户密钥文件的实际路径（如果您使用服务账户认证）。
'YOUR_DEVELOPER_TOKEN_HERE' 和 'YOUR_MANAGER_ACCOUNT_ID_HERE' 替换为您的 Google Ads API 开发者令牌和管理员账户 ID（如果适用）。
'command' 和 'args' 字段指定了启动 MCP 服务器的命令。'env' 字段用于设置服务器运行所需的环境变量。
将上述 JSON 配置信息添加到 Claude Desktop 的 'claude_desktop_config.json' 文件或 Cursor 的 '.cursor/mcp.json' 配置文件中，即可让客户端连接到此 MCP 服务器。具体操作请参考 README.md 文档中 "5. Connect Claude to Google Ads" 和 "5a. Connect to Cursor" 章节。

基本使用方法

配置完成后，在 Claude Desktop 或 Cursor 中，即可通过自然语言指令调用 Google Ads MCP 服务器提供的工具，例如：

询问 Claude "列出我的 Google Ads 账户" (对应 'list_accounts' 工具)。
询问 Claude "过去 30 天，账户 [customer_id] 的广告系列效果如何？" (可能触发 'get_campaign_performance' 工具)。
使用更具体的指令，例如 "使用 Google Ads MCP 工具运行 GAQL 查询，获取点击次数超过 100 的广告组" (对应 'run_gaql' 工具)。

具体可使用的工具和示例指令，请参考 README.md 文档中 "Available Tools" 和 "6. Start Analyzing Your Advertising Data!" 章节。

关键词