← 返回指南

指南 / codex

如何用 Codex 连接 Google Ads MCP：环境配置与首次只读分析

从 Codex、Python、Google Cloud 和开发者令牌准备开始，逐步连接官方 Google Ads MCP，并完成首次只读账户与广告表现查询。

作者：AdsDecide更新于 2026-08-20

这篇教程将带你把 Codex 连接到 Google 官方开源的 Google Ads MCP 服务器。完成后，你可以让 Codex 列出有权访问的 Google Ads 客户账户，并使用自然语言查询广告系列表现。

Google 目前提供的是需要在本机启动的官方 MCP 服务器，而不是所有人都能直接粘贴的公共服务器地址。因此，它比 Meta Ads MCP 多一些账户和开发环境准备。已有 Google Ads 开发者令牌的用户通常可以在 20–40 分钟内完成；开发者令牌的申请或升级可能需要额外等待。

完成后你会得到什么

  • Codex 的 MCP 列表中显示 Google Ads 已连接。
  • Codex 能列出当前 Google 用户直接有权访问的客户 ID。
  • Codex 能按目标账户的时区和币种查询最近 7 个完整自然日的广告表现。
  • 你会完成一次只读报表查询，并确认过程中没有改动广告账户。

开始前的准备清单

需要准备最低要求如何确认
Codex已安装可使用 Codex 的桌面应用可以在 Codex 中新建会话
PythonPython 3.10 或更高版本终端执行 python3 --version 或 Windows 的 py --version
pipx能在终端运行 pipx执行 pipx --version
Google Cloud CLI能在终端运行 gcloud执行 gcloud --version
Google Ads 客户账户Google 用户能打开目标广告账户记下不含连字符的 10 位客户 ID
Google Ads 经理账户用于获取开发者令牌登录后能打开 Google Ads API 中心
开发者令牌至少能访问你准备查询的账户环境在 API 中心查看令牌和访问级别
Google Cloud 项目可以启用 API 和创建 OAuth 客户端记下项目 ID，不要只记项目名称

不要把开发者令牌、OAuth 客户端文件或应用默认凭据（ADC）放进项目目录、Git 仓库或 Codex 提示词。

第 1 步：确认 Google Ads 账户和开发者令牌

1.1 记录客户账户 ID

打开目标 Google Ads 账户，记录右上角或账户选择器中的 10 位客户 ID。配置和提示词中应删除连字符：

界面显示：123-456-7890
配置使用：1234567890

如果你通过经理账户管理客户账户，还要记录经理账户的 10 位客户 ID。后文会把它填入 GOOGLE_ADS_LOGIN_CUSTOMER_ID。

1.2 获取开发者令牌

  1. 登录 Google Ads 经理账户。
  2. 打开 Google Ads API 中心。普通客户账户没有 API 中心。
  3. 如果已经有开发者令牌，记录它的状态和访问级别。
  4. 如果没有，提交 API 访问权限申请。

查询生产账户通常需要探索者、基本或标准访问权限。只有测试账户访问权限时，可以先完成本教程，但只能查询 Google Ads 测试账户。不要在开发者令牌尚未获准访问生产账户时反复修改 MCP 配置。

检查点： 你应拥有开发者令牌、它的访问级别、目标客户 ID，以及需要时使用的经理账户 ID。详细规则见 Google Ads 开发者令牌官方说明。

第 2 步：安装本地工具

Google 官方 MCP 要求 Python 3.10 或更高版本，并通过 pipx 启动。应用默认凭据登录还需要 Google Cloud CLI。

macOS

推荐使用 Homebrew 一次安装所需工具：

  1. 打开 macOS 的“终端”应用。
  2. 执行 brew --version 检查是否已经安装 Homebrew。如果提示找不到命令，先按照 Homebrew 官网的说明完成安装，然后重新打开终端。
  3. 安装 Python 3.10 或更高版本以及 pipx：
brew install python pipx
  1. 让终端可以直接找到 pipx：
pipx ensurepath
  1. 安装 Google Cloud CLI：
brew update
brew install --cask gcloud-cli
  1. 关闭并重新打开终端。暂时不要继续配置，先完成本节末尾的版本检查。

如果不使用 Homebrew，也可以从 Python 官网安装 Python，并按照 Google Cloud CLI 的 macOS 安装说明安装 gcloud；之后仍需单独安装 pipx。

Windows

从 Python 官网安装 Python 3.10+，安装时勾选将 Python 添加到 PATH。然后在 PowerShell 中运行：

py -m pip install --user pipx
py -m pipx ensurepath

再按 Google Cloud CLI Windows 安装说明完成安装。

Linux

先通过系统包管理器安装 Python 3.10+ 和 pip，然后运行：

python3 -m pip install --user pipx
python3 -m pipx ensurepath

再按 Google Cloud CLI Linux 安装说明安装 gcloud。

安装完成后关闭并重新打开终端，再执行：

python3 --version
pipx --version
gcloud --version

Windows 如果没有 python3 命令，使用 py --version。三个命令都能输出版本号后再继续。

第 3 步：准备 Google Cloud 项目和 OAuth

3.1 创建项目并启用 Google Ads API

  1. 打开 Google Cloud 控制台。
  2. 创建或选择一个专门用于此连接的项目。
  3. 复制项目 ID，例如 my-ads-analysis-123。项目显示名称不能替代项目 ID。
  4. 打开 Google Ads API 页面，确认当前选择的是正确项目，然后点击启用。

3.2 创建桌面应用 OAuth 客户端

  1. 在 Google Cloud 控制台中打开Google 身份验证平台。
  2. 如果尚未配置，先填写应用名称、支持邮箱和受众。
  3. 在 OAuth 授权范围中加入 Google Ads API 授权范围：
https://www.googleapis.com/auth/adwords
  1. 如果应用处于测试状态，把稍后登录的 Google 账户加入测试用户。
  2. 创建新的 OAuth 客户端，在应用类型中选择桌面应用。
  3. 下载客户端 JSON，保存到本机的私有目录，例如：
/Users/your-name/.config/google-ads/client_secret.json

不要把 JSON 放进当前项目或任何会被 Git 同步的目录。

3.3 创建应用默认凭据

在终端把 YOUR_PROJECT_ID 替换为项目 ID：

gcloud config set project YOUR_PROJECT_ID

再把 YOUR_CLIENT_JSON_FILE 替换为刚才下载文件的绝对路径：

gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=YOUR_CLIENT_JSON_FILE

浏览器打开后，登录能够访问目标 Google Ads 账户的 Google 用户并完成授权。终端成功时会显示类似：

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

复制方括号中的凭据文件绝对路径，下一步需要使用它。不要打开或复制凭据文件内容。

检查点： 你现在应有三项值：PATH_TO_CREDENTIALS_JSON、YOUR_PROJECT_ID 和 YOUR_DEVELOPER_TOKEN。

第 4 步：在 Codex 中添加 Google Ads MCP

  1. 打开 Codex 的设置。
  2. 选择 MCP 服务器。
  3. 点击添加服务器。
  4. 在名称中填写 Google Ads，类型选择 STDIO。
  5. 在命令中填写：
pipx
  1. 在参数中按顺序添加以下四项：
run
--spec
git+https://github.com/googleads/google-ads-mcp.git
google-ads-mcp
  1. 添加环境变量：
变量名值
GOOGLE_APPLICATION_CREDENTIALS应用默认凭据命令返回的凭据文件绝对路径
GOOGLE_PROJECT_IDGoogle Cloud 项目 ID
GOOGLE_ADS_DEVELOPER_TOKENGoogle Ads 开发者令牌
GOOGLE_ADS_LOGIN_CUSTOMER_ID可选；通过经理账户访问时填写不含连字符的经理账户 ID
  1. 如果界面允许设置启动超时，将其设为 120 秒。第一次启动时 pipx 需要从官方 GitHub 仓库下载服务和依赖。
  2. 保存并点击重新启动。

如果界面没有分开的参数或环境变量输入框，可以编辑全局 ~/.codex/config.toml：

[mcp_servers.google_ads]
command = "pipx"
args = [
  "run",
  "--spec",
  "git+https://github.com/googleads/google-ads-mcp.git",
  "google-ads-mcp",
]
startup_timeout_sec = 120
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

[mcp_servers.google_ads.env]
GOOGLE_APPLICATION_CREDENTIALS = "PATH_TO_CREDENTIALS_JSON"
GOOGLE_PROJECT_ID = "YOUR_PROJECT_ID"
GOOGLE_ADS_DEVELOPER_TOKEN = "YOUR_DEVELOPER_TOKEN"
# 仅在通过经理账户访问客户账户时取消下一行注释：
# GOOGLE_ADS_LOGIN_CUSTOMER_ID = "YOUR_MANAGER_CUSTOMER_ID"

替换所有大写占位符后再重启 Codex。这个文件包含敏感信息，只能放在你的本机用户目录，不能复制到项目级 .codex/config.toml 或提交到 Git。

第 5 步：确认 MCP 已连接

第一次启动可能需要一两分钟。新建 Codex 会话并输入：

/mcp

找到 Google Ads，确认服务器已经启用，并能看到客户账户列表、搜索和资源元数据等工具。

检查点： 如果服务器出现在列表中且没有启动错误，说明 Python 服务已成功运行。看到服务但查询失败，通常说明下一层的 Google 凭据或账户权限仍需检查。

第 6 步：列出可以访问的客户账户

复制下面的提示词：

请仅使用 Google Ads MCP 的只读工具，列出当前认证用户直接有权访问的
Google Ads 客户 ID。

请返回每个客户 ID，并说明它是客户账户还是经理账户；如果工具不能
返回账户名称或类型，请明确标记“不可用”，不要猜测。

不要创建或修改广告系列、广告组、广告、关键词、出价或预算。

Google Ads 的可访问客户接口只列出当前用户直接访问的账户，不会自动展开经理账户下的全部子账户。看到经理账户 ID 但没看到某个客户账户，不一定代表授权失败；下一步可以明确提供目标客户 ID 和 GOOGLE_ADS_LOGIN_CUSTOMER_ID。

第 7 步：运行第一次只读广告分析

把 1234567890 替换为不含连字符的目标客户账户 ID：

请仅使用 Google Ads MCP 的只读搜索工具分析客户 ID 1234567890。

查询要求：
1. 先查询并确认 customer.id、customer.descriptive_name、
   customer.time_zone 和 customer.currency_code。
2. 按该账户时区计算“截至昨天的最近 7 个完整自然日”，明确写出开始日期
   和结束日期，不要包含今天。
3. 按广告系列查询 campaign.id、campaign.name、campaign.status、
   campaign.advertising_channel_type、metrics.cost_micros、
   metrics.impressions、metrics.clicks、metrics.ctr、metrics.average_cpc、
   metrics.conversions、metrics.cost_per_conversion、metrics.conversions_value
   和 metrics.conversions_value_per_cost。
4. 把 cost_micros 和 average_cpc 从 micros 转换为账户币种，按消耗从高到低
   排序，并增加总计。
5. 如果某个字段不兼容或没有返回，标记“不可用”并说明原因，不要把缺失值
   当成 0，也不要擅自更换指标。
6. 最后用不超过 3 条要点指出值得人工复核的变化，但不要执行任何优化。

不要创建或修改广告系列、广告组、广告、关键词、出价或预算。

一份可靠的首次结果应同时显示：

  • 目标客户 ID 和账户名称。
  • 账户时区、币种和明确的开始/结束日期。
  • micros 已转换成正常货币单位。
  • 报表字段、筛选条件以及缺失字段。
  • 数据结论与执行建议分开。

常见问题与最快排查顺序

Codex 提示找不到 pipx

关闭并重新打开 Codex 与终端，让 pipx ensurepath 的 PATH 修改生效。在终端确认 pipx --version 成功；Windows 还可以先执行 py -m pipx --version 判断是否只是 PATH 问题。

MCP 启动超时

第一次运行需要从 GitHub 下载依赖。确认网络可以访问 github.com/googleads/google-ads-mcp，把 startup_timeout_sec 保持为 120，然后重启。不要同时重复添加多个相同服务器。

提示 Google Ads API 未启用

打开 Google Cloud 控制台，确认当前项目与 GOOGLE_PROJECT_ID 完全一致，并在该项目中启用 Google Ads API。启用后等待几分钟再试。

提示开发者令牌只能访问测试账户

开发者令牌当前只有测试账户访问权限。改用测试账户完成验证，或在 API 中心申请探索者、基本或标准访问权限；修改客户 ID 无法绕过这个限制。

提示 USER_PERMISSION_DENIED 或账户列表为空

确认应用默认凭据登录使用的 Google 用户可以在浏览器中打开该 Google Ads 账户。OAuth 客户端、开发者令牌和 Google Ads 用户权限是三个不同层级，拥有开发者令牌不代表自动拥有客户账户访问权。

通过经理账户访问时查询失败

检查 GOOGLE_ADS_LOGIN_CUSTOMER_ID 是否为不含连字符的经理账户 ID，查询提示词中的客户 ID 是否为真正的客户账户。修改环境变量后必须重启 Codex。

数据为空或与 Google Ads 界面不一致

先确认账户在日期范围内有消耗，再核对账户时区、转化操作、归因口径、币种、广告系列状态和今天是否被排除。要求 Codex 返回实际生成的查询字段和日期条件。

凭据与执行安全

  • 开发者令牌、OAuth 客户端 JSON 和应用默认凭据文件都应按密码管理。
  • 不要把真实令牌或凭据内容粘贴到提示词、工单、截图或 Git 仓库。
  • 使用全局 ~/.codex/config.toml，不要把凭据写进项目级配置。
  • 如果怀疑开发者令牌泄露，立即在 Google Ads API 中心重置。
  • 本教程只查询数据；即使未来服务器增加写入工具，也应单独审批每次变更。

官方参考资料

配置完成后，Codex 每次启动都会按这套设置运行 Google Ads MCP。后续提问只需提供正确的客户 ID、完整日期范围、指标和只读约束，不必重新安装服务。