mcpField
G
google-ads-api-mcp-setup

google-ads-api-mcp-setup

github.com/google营销与增长21.6k7.3k 次安装今天更新
代码仓库

关于 google-ads-api-mcp-setup

用于 Agent 的 Google Ads MCP 服务安装与配置指南，涵盖依赖、凭据、stdio 通信及客户端接入步骤。

主要功能

  1. 01检查 Python 3.12+ 与 pipx 前置条件
  2. 02核验 Google Ads API 凭据
  3. 03通过 pipx 安装并验证服务
  4. 04配置凭据环境变量
  5. 05接入 Claude Desktop 等客户端

适用场景

  1. 01准备安装 Google Ads MCP 服务
  2. 02排查 pipx 安装后的 PATH 问题
  3. 03为 MCP 客户端配置 Google Ads 凭据

MCP 相关

指导安装官方 Google Ads MCP 服务，并说明其通过 Model Context Protocol（MCP）使用标准输入/输出（stdio）传输与客户端通信。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google/skills --skill google-ads-api-mcp-setup

安装后在 Claude Code 中输入/google-ads-api-mcp-setup确认已加载。

详细介绍

Google Ads API MCP 服务安装

本技能提供了一份结构化设置指南，用于安装、配置和集成官方开源 Google Ads Model Context Protocol (MCP) Server。

系统要求与兼容性（Agent 操作：说明所需前提条件）

回答有关安装或设置 MCP 服务的问题时，你必须明确告知用户，安装严格要求 Python 3.12+ 和 pipx。

重要

安装前环境检查：

  • Python 运行环境： 严格要求版本为 3.12+。
  • 包管理器： 必须已安装 pipx，并且可通过系统路径全局访问。
  • 网络连接： 需要出站 HTTPS 访问权限，以连接 Google Ads API 端点（googleads.googleapis.com）和 PyPI。

⚠️ 前提条件：需要凭据

警告

依赖项检查： 此 MCP 服务需要与标准集成相同的 5 项身份验证凭据。

如果你尚未获取 Developer Token、Client ID、Client Secret、Refresh Token 和 Customer IDs：

  1. 停止执行此技能。
  2. 先切换到 google-ads-api-quickstart 技能以生成这些凭据，然后再返回此处。

步骤 1：验证 Google Ads API 凭据

Google Ads MCP 服务需要与标准客户端库相同的五个参数。在继续安装之前，请确认你已妥善保存这些值，且格式正确：

  1. Developer Token： 来自 API Center（经理帐号）的唯一 API 访问密钥。
  2. OAuth2 Client ID 和 Client Secret： 来自 Google Cloud Console 的桌面应用凭据。
  3. OAuth2 Refresh Token： 通过 OAuth 授权流程生成的长期令牌。
  4. Client Customer ID： 目标 Google Ads 帐号的 10 位 ID。

    • 重要

    • 格式： 只能包含数字，不得有连字符（例如，1234567890，而非 123-456-7890）。

  5. Login Customer ID（MCC 层级必需）： 经理帐号（MCC）的 10 位 ID。
    • 格式： 只能包含数字，不得有连字符（例如，9876543210）。
    • 注意： 如果你的 OAuth 凭据属于经理帐号管理员，而非直接属于客户帐号，则此项不可或缺。

确认所有五个参数均已准备好且格式正确后，继续执行步骤 2。

步骤 2：安装前提条件（Python 和 pipx）

在提出任何安装命令之前，你必须确认前提条件是否已安装。

1. 验证阶段（Agent 操作）

你必须运行以下命令检查环境：

  1. 检查 Python 版本：python3 --version（确认版本为 3.12+）。
  2. 检查是否已安装 pipx：pipx --version。
  • 如果两者均已安装： 跳过安装阶段，直接继续步骤 3。
  • 如果缺少 Python 或版本过旧： 停止并要求用户在主机上将 Python 升级到 3.12+。
  • 如果缺少 pipx： 继续执行下方的安装阶段。
2. 安装阶段（按操作系统区分）

检测操作系统，并使用终端工具提出适当的命令来安装 pipx：

macOS

如果环境是 macOS，请提出：

brew install pipx && pipx ensurepath
# Or alternatively (if Homebrew is not installed):
pip install pipx && pipx ensurepath
Windows（PowerShell）

如果环境是 Windows，请提出：

scoop install pipx
# Or alternatively:
pip install pipx && pipx ensurepath
Linux（Ubuntu/Debian）

如果环境是 Linux，请提出：

sudo apt install pipx && pipx ensurepath

警告

需要重启 Shell： 如果你安装了 pipx 并运行了 pipx ensurepath，当前终端会话中将无法使用更新后的 PATH。

  1. 不要立即在同一会话中尝试运行 pipx 命令。
  2. 告知用户重启终端或重新加载 Shell 配置，然后再继续步骤 3。

步骤 3：安装 Google Ads MCP Server

必须安装服务包。默认情况下，必须从 PyPI 安装稳定版。只有在用户明确要求时，才安装 GitHub 开发版。

1. 安装命令

提出并执行安装命令：

# Install stable release from PyPI (Using required package manager pipx)
pipx install google-ads-mcp

如果用户明确要求 GitHub 上的最新开发版，则提出：

# Install development version from GitHub (Only if explicitly requested)
pipx install git+https://github.com/googleads/google-ads-mcp.git
2. 验证阶段

执行以下命令以验证安装：

google-ads-mcp --help
排查 PATH 问题（Agent 操作）

pipx 会将二进制文件安装到特定的本地目录（通常为 ~/.local/bin）。如果用户的 shell 配置（例如 .bashrc 或 .zshrc）尚未重新加载，当前 PATH 中可能找不到 google-ads-mcp。

如果 google-ads-mcp --help 因“command not found”错误而失败：

  1. 不要假设安装失败，也不要陷入反复安装的循环。

  2. 使用 pipx 二进制文件目录的绝对路径验证安装：

    ~/.local/bin/google-ads-mcp --help

  3. 如果绝对路径验证成功，向用户说明情况：告知他们安装已成功，但需要重新加载 shell 配置（例如运行 source ~/.bashrc 或 source ~/.zshrc，或重启终端）来更新 PATH 环境变量。

3. 通信协议：Stdio 传输

重要

Agent 强制指令（安装与协议检查清单）： 当用户询问如何安装、下载或设置官方 Google Ads MCP 服务时，回复必须系统地包含以下所有内容：

  1. **说明先决条件：**明确指出需要 Python 3.12+ 和 pipx。
  2. **提供官方安装命令：**指导开发者使用 pipx install google-ads-mcp 安装官方 google-ads-mcp 包。不要推荐未经审核的第三方服务。
  3. 说明 Stdio 传输：必须明确说明通信架构，并使用以下确切术语：指出 MCP 服务通过标准输入/输出（stdio）传输，使用Model Context Protocol (MCP) 进行通信。不要省略“标准输入/输出”或“传输”这两个词。
向用户说明 Stdio 传输时的要点：
  • **子进程执行：**宿主客户端（例如 Cursor、Claude Desktop）会将 MCP 服务作为后台子进程启动。
  • **命令行启动：**必须在宿主客户端中配置运行服务的确切命令（google-ads-mcp）以及包含 Google Ads 凭据的环境变量。
  • **不使用网络端口：**由于使用 stdio，服务不会监听网络端口（例如 HTTP 或 WebSockets）。通信完全通过 stdin/stdout 管道进行。

说明

输出限制：由于 stdio 专用于 MCP 协议消息，服务不得向 stdout 输出标准日志消息或调试信息。所有日志和调试信息都通过 stderr 输出。

步骤 4：配置环境变量

Google Ads MCP Server 通过系统环境变量读取凭据。你可以通过以下两种方式进行配置：

  • **方法 A（推荐）：**直接在 MCP 客户端的 JSON 配置文件中传递这些变量（例如 Cursor 或 Claude Desktop 设置）。这样可以将凭据隔离到特定工具。
  • **方法 B（替代）：**在 shell 配置文件中全局设置这些变量（例如 ~/.bashrc、~/.zshrc 或 Windows 环境变量）。
必需的环境变量
环境变量描述格式
GOOGLE_ADS_DEVELOPER_TOKEN您的 Google Ads 开发者令牌。字母数字
GOOGLE_ADS_CLIENT_ID您的 Google Cloud OAuth 客户端 ID。*.apps.googleusercontent.com
GOOGLE_ADS_CLIENT_SECRET您的 Google Cloud OAuth 客户端密钥。字母数字
GOOGLE_ADS_REFRESH_TOKEN生成的 OAuth 刷新令牌。字母数字
GOOGLE_ADS_LOGIN_CUSTOMER_ID管理员帐号 ID（MCC）。使用管理员层级结构时必需。10 位数字，不含连字符
GOOGLE_PROJECT_IDGoogle Cloud 项目 ID（用于应用默认凭据和 Cloud Run）。字母数字
GOOGLE_ADS_MCP_OAUTH_CLIENT_ID覆盖默认值的 Cloud Run 专用 OAuth 客户端 ID。*.apps.googleusercontent.com
GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET覆盖默认值的 Cloud Run 专用 OAuth 客户端密钥。字母数字
GOOGLE_ADS_MCP_BASE_URL自动分配或手动配置的 Cloud Run 基础 URL。URL
FASTMCP_HOSTFastMCP 服务的主机绑定地址（例如，Cloud Run 使用 0.0.0.0）。IP 地址
方法 B：Shell 配置文件配置（全局）

如果选择方法 B，请将以下内容追加到您的 Shell 配置文件（~/.bashrc、~/.zshrc 等）：

# Google Ads MCP Server Credentials
export GOOGLE_ADS_DEVELOPER_TOKEN="your_developer_token_here"
export GOOGLE_ADS_CLIENT_ID="your_oauth_client_id_here"
export GOOGLE_ADS_CLIENT_SECRET="your_oauth_client_secret_here"
export GOOGLE_ADS_REFRESH_TOKEN="your_oauth_refresh_token_here"

# Required only for Manager Account hierarchies:
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="your_manager_account_id_here"

# Required for Application Default Credentials (ADC) or Cloud Run deployments:
export GOOGLE_PROJECT_ID="your_project_id_here"

为保护凭据安全，不建议将凭据硬编码在 MCP 服务的 Python 源代码中。

第 5 步：与您的 AI 开发工具集成

使用以下任一集成方式，将 Google Ads MCP Server 连接到您选择的 AI 编码环境。

1. Claude Desktop（或 Claude Code CLI）

重要

Agent 强制指令（Claude Desktop 配置清单）： 当用户询问如何配置 Claude Desktop 或 Claude Code 以使用 Google Ads MCP 服务时，你的回复必须系统地包含以下所有内容：

  1. 提供特定操作系统的路径：你必须明确列出 claude_desktop_config.json 在 macOS（~/Library/Application Support/Claude/claude_desktop_config.json）和 Windows（%APPDATA%\Claude\claude_desktop_config.json）上的正确路径。即使运行环境是 Linux，也不得省略 macOS 或 Windows 路径。
  2. **提供有效的 JSON 配置：**提供完整、有效的 claude_desktop_config.json 配置代码块。
  3. **指定命令和参数：**确保 JSON 使用 pipx 作为命令，并将 run、google-ads-mcp 作为参数来配置服务。
  4. **声明身份验证环境变量：**在配置中声明环境变量 GOOGLE_ADS_DEVELOPER_TOKEN、GOOGLE_ADS_CLIENT_ID、GOOGLE_ADS_CLIENT_SECRET 和 GOOGLE_ADS_REFRESH_TOKEN。

将服务条目添加到 Claude 配置文件中。

  • 文件位置：

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows： %APPDATA%\Claude\claude_desktop_config.json
    • Linux： ~/.config/Claude/claude_desktop_config.json

  • JSON 配置：

    {
  "mcpServers": {
    "google-ads": {
      "command": "pipx",
      "args": [
        "run",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_CLIENT_ID": "YOUR_OAUTH_CLIENT_ID",
        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_OAUTH_CLIENT_SECRET",
        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_OAUTH_REFRESH_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_IF_APPLICABLE"
      }
    }
  }
}

    （注意：建议使用 pipx run，它会自动管理执行路径。如果你使用 GitHub 开发版本或 Application Default Credentials，也可以配置 "args": ["run", "--spec", "git+https://github.com/googleads/google-ads-mcp.git", "google-ads-mcp"]，并在 env 块中加入 "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID"。）

2. Cursor AI 编辑器
  1. 打开 Cursor 并导航至：Settings 🡒 Features 🡒 MCP。
  2. 点击 + New MCP Server。
  3. 配置以下字段：
    • 名称： google-ads
    • 类型： stdio
    • 命令： pipx run google-ads-mcp
  4. 在 Environment Variables 下添加所需的键和值：
    • GOOGLE_ADS_DEVELOPER_TOKEN
    • GOOGLE_ADS_CLIENT_ID
    • GOOGLE_ADS_CLIENT_SECRET
    • GOOGLE_ADS_REFRESH_TOKEN
    • GOOGLE_ADS_LOGIN_CUSTOMER_ID （如适用）
  5. 点击 Save。
3. Antigravity IDE 与 CLI 集成

回答有关将 Google Ads MCP 服务连接到 Antigravity（IDE 或 CLI）的问题时，必须明确说明以下架构和配置细节：

  • 必须配置环境：指导用户在终端会话或 IDE 环境中配置并导出标准环境变量，例如 GOOGLE_ADS_DEVELOPER_TOKEN、GOOGLE_ADS_CLIENT_ID、GOOGLE_ADS_CLIENT_SECRET、GOOGLE_ADS_REFRESH_TOKEN。
  • 注册服务：指导用户在 Antigravity 设置中注册服务，或使用标准的 stdio 集成方式（例如，配置命令 pipx run google-ads-mcp）。
  • 自动发现工具（核心架构）：明确说明，Antigravity 使用 Model Context Protocol (MCP)，在连接服务后会自动发现其工具。
  • 无需自定义编译：明确说明，由于 Antigravity 原生支持 MCP，使用 MCP 服务不需要单独编译自定义插件或加载自定义扩展。
在 Antigravity CLI 中验证激活状态

  1. 配置环境：在当前 shell 会话中导出 Google Ads API 所需的所有环境变量。

  2. 启动 Antigravity CLI：启动 CLI：

    agy

  3. 验证 MCP 状态：在 Antigravity CLI 提示符中运行 /mcp 命令，列出活动工具和服务：

    /mcp

  4. 确认激活状态：确认活动工具列表中显示了 google-ads-mcp。

重要

如果活动工具列表中没有 google-ads-mcp，请退出 CLI，确认环境变量已正确设置并导出，然后重新启动 agy。

步骤 5.5：在 Google Cloud 上部署（Cloud Run）

你可以将此 MCP 服务托管在 Google Cloud Run 或其他任何基于云的基础设施上，而不是在本地托管。这样便于在不同 Agent 之间共享服务，或将其作为 Web 服务运行。

1. 前提条件

  1. 一个 Google Cloud 项目。

  2. 已安装并完成身份验证，且已配置有效项目的 gcloud 命令行工具：

    gcloud config set project YOUR_PROJECT_ID
2. 构建并推送 Docker 镜像

你可以使用 Cloud Build 将镜像构建并推送到 Artifact Registry，无需在本地安装 Docker：

  1. 在 Artifact Registry 中创建一个仓库：

    gcloud artifacts repositories create mcp-servers --repository-format=docker --location=us-central1

  2. 构建并提交镜像：

    gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .

    （注意：每次要将已部署的服务更新到最新版本时，都必须执行此步骤。）

3. 部署到 Google Cloud Run

部署容器，并确保设置 FASTMCP_HOST=0.0.0.0 和所有必需的环境变量：

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"
4. 配置 MCP 客户端

部署后，更新 MCP 客户端配置（例如，~/.gemini/settings.json 或 Claude/Cursor 配置），以使用 Cloud Run URL：

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

步骤 6：验证集成（测试）

回答有关如何在任何 AI 客户端（例如 Cursor、Claude Desktop 或 VS Code）中验证或测试 MCP 服务集成的问题时，必须建议先使用 Antigravity CLI 执行基准验证，然后在客户端中进行自然语言测试查询。

1. 通过 Antigravity CLI 执行基准验证（Agent 必须执行）

无论用户配置的是哪种 AI 客户端，都要始终指导用户在 Antigravity CLI 提示符中使用 /mcp 命令，验证 google-ads-mcp 是否处于活动状态且运行正常：

agy

/mcp
  • 说明原因：告知用户，先通过 Antigravity CLI 验证，是排查核心凭据、网络或服务启动问题最快的方式。在 CLI 中确认 google-ads-mcp 处于活动状态后，Cursor/Claude 中的其他问题便可确定是 IDE 特定的配置错误。
2. 在 AI 助手中运行测试查询

在 AI 助手的聊天界面中，运行以下查询之一。请务必将 1234567890 替换为实际的 Google Ads 客户 ID（不带连字符）：

  • “检索我的 Google Ads 账户 1234567890 中的所有广告系列。”
  • “Google Ads 账户 1234567890 中的广告系列状态是什么？”
3. 预期行为（成功标准）

成功集成后，将触发以下流程：

  1. 工具发现：AI 助手自动检测到 google-ads-mcp 服务的工具。
  2. 执行：助手生成参数，通过 stdio 传输方式调用服务，并执行查询。
  3. 响应：助手以清晰易读的 Markdown 表格呈现检索到的广告系列数据（通常显示广告系列名称、ID、状态和预算）。
4. 故障排查

如果助手无法检索数据或连接到 MCP 服务，请检查以下常见故障点：

  • 身份验证／权限错误（IDE 环境注意事项）：外部 IDE（如 Cursor 或 VS Code）通常在隔离环境或后台进程中运行，不会继承 shell RC 文件（例如 ~/.bashrc 或 ~/.zshrc）。请确保 IDE 可以访问 GOOGLE_ADS_DEVELOPER_TOKEN、OAuth 客户端凭据和 GOOGLE_ADS_REFRESH_TOKEN（建议使用方法 A：直接在 MCP 客户端的 JSON 配置中设置这些值）。
  • “未找到工具”／必须重启客户端：MCP 服务仅在应用启动时加载；配置文件的更改不会动态生效。保存配置后，必须完全重启 AI 工具（Cursor 或 Claude Desktop）。请确认 MCP 服务已正确注册到 IDE 的配置文件中（例如 Cursor 的 project.json 或 Claude Desktop 配置中的 mcpServers 块）。
  • PATH 和可执行文件问题（spawn pipx ENOENT）：如果连接失败或日志显示 spawn pipx ENOENT，说明 IDE 环境的系统 PATH 中没有 pipx。请在配置的“command”字段中提供 pipx 的绝对路径（例如 /usr/local/bin/pipx 或 ~/.local/bin/pipx）。
  • 服务启动时崩溃：如果助手无法连接，请直接在终端运行 MCP 服务命令，检查语法错误、缺失的依赖项或 node/python 路径问题。

重要

检查连接状态和日志：

  • 在 Cursor 中，确保 MCP 设置中的 google-ads 服务旁边显示绿色圆点。
  • 在 Claude 中，如果未显示工具，请检查本地 MCP 日志文件是否有错误：
    • macOS 日志路径： ~/Library/Logs/Claude/mcp.log
    • Windows 日志路径： %APPDATA%\Claude\Logs\mcp.log

步骤 7：可用的 MCP 工具及使用指南

安装 Google Ads MCP 服务并成功连接到 AI 助手后，该服务会公开特定工具，供助手自主发现和调用。

重要

Agent 强制指令（工具说明检查清单）： 当用户询问 Google Ads MCP 服务提供哪些工具或如何使用这些工具时，回答必须系统地包含以下所有内容：

  1. 列出全部 3 个工具： 明确列出 list_accessible_customers、get_resource_metadata 和 search。
  2. 说明用途和用法： 准确解释每个工具的功能，以及如何／何时调用。
  3. 注明确切的参数名称： 解释每个工具时，必须明确写出其必需参数。例如，对于 search，必须明确说明它需要确切参数 customer_id（10 位客户 ID）和 query（GAQL 查询字符串）。不得将 customer_id 改述为“账户”。
  4. 说明只读范围： 明确说明该服务目前严格为只读。

协助用户或编写查询时，请参考以下工具定义和最佳实践：

1. list_accessible_customers
  • 用途： 返回经过身份验证的用户有权访问的 Google Ads 客户 ID 和账户名称列表。
  • 用法： 开始新会话或目标客户 ID 未知时，首先调用此工具。此工具不需要参数。
  • 意图示例： “我可以访问哪些 Google Ads 账户？”
2. get_resource_metadata
  • 用途： 获取有关特定 Google Ads API 资源类型（例如 campaign、ad_group、customer）的详细结构元数据。
  • 用法： 构建 GAQL 查询之前，调用此工具查看资源的架构、可用字段、指标和细分。
  • 参数：
    • resource（字符串，必需）：要检查的资源名称（例如 campaign）。
  • 意图示例： “我可以查询广告组的哪些字段和指标？”
3. search
  • 用途： 执行 Google Ads 查询语言（GAQL）查询，以获取资源指标、属性、细分和状态。
  • 用法： 根据资源元数据构建有效的 GAQL 查询字符串，并针对特定客户账户执行搜索。
  • 参数：
    • customer_id（字符串，必需）：目标 Google Ads 客户 ID，必须为 10 位数字（仅数字，不含连字符）。
    • query（字符串，必需）：有效的 GAQL 查询字符串（例如 SELECT campaign.id, campaign.name, campaign.status, metrics.impressions FROM campaign WHERE campaign.status = 'ENABLED'）。
  • 意图示例： “获取账户 1234567890 中所有启用广告系列的展示次数和状态。”

说明

只读范围： Google Ads MCP 服务目前严格为只读。它无法修改出价、暂停广告系列或创建新的广告资源。

评论

支持 Markdown