指南 / codex

如何用 Codex 连接 Google Ads MCP：官方完整教程

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

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

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

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

完成后你会得到什么

Codex 的 MCP 列表中显示 Google Ads 已连接。
Codex 能列出当前 Google 用户直接有权访问的 Customer ID。
Codex 能按目标账户的时区和币种查询最近 7 个完整自然日的广告表现。
整个教程只使用官方 MCP 的读取和报表能力，不修改广告账户。

开始前的准备清单

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

不要把 Developer Token、OAuth 客户端文件或 ADC 凭据放进项目目录、Git 仓库或 Codex Prompt。

第 1 步：确认 Google Ads 账户和 Developer Token

1.1 记录客户账户 ID

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

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

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

1.2 获取 Developer Token

登录 Google Ads Manager Account。
打开 Google Ads API Center。普通客户账户没有 API Center。
如果已经有 Developer Token，记录它的状态和 Access level。
如果没有，提交 API Access 申请。

查询生产账户通常需要 Explorer、Basic 或 Standard Access。只有 Test Account Access 时，可以先完成本教程，但只能查询 Google Ads 测试账户。不要在 Token 尚未获准访问生产账户时反复修改 MCP 配置。

检查点： 你应拥有 Developer Token、它的 Access level、目标 Customer ID，以及需要时使用的 Manager Customer ID。详细规则见 Google Ads Developer Token 官方说明。

第 2 步：安装本地工具

Google 官方 MCP 要求 Python 3.10 或更高版本，并通过 pipx 启动。ADC 登录还需要 Google Cloud CLI。

macOS

先安装 Python 3.10+；如果已经使用 Homebrew，可以运行：

brew install python pipx
pipx ensurepath
brew install --cask google-cloud-sdk

Windows

从 Python 官网安装 Python 3.10+，安装时勾选 Add Python to 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

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

3.2 创建 Desktop App OAuth Client

在 Google Cloud Console 中打开 Google Auth Platform。
如果尚未配置，先填写应用名称、支持邮箱和受众。
在 OAuth Scopes 中加入 Google Ads API scope：

https://www.googleapis.com/auth/adwords

如果应用处于 Testing 状态，把稍后登录的 Google 账户加入 Test users。
创建新的 OAuth Client，Application type 选择 Desktop app。
下载客户端 JSON，保存到本机的私有目录，例如：

/Users/your-name/.config/google-ads/client_secret.json

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

3.3 创建 Application Default Credentials

在终端把 YOUR_PROJECT_ID 替换为 Project 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

打开 Codex 的 Settings。
选择 MCP servers。
点击 Add server。
Name 填写 Google Ads，Type 选择 STDIO。
Command 填写：

pipx

Arguments 按顺序添加以下四项：

run
--spec
git+https://github.com/googleads/google-ads-mcp.git
google-ads-mcp

添加环境变量：

变量名	值
`GOOGLE_APPLICATION_CREDENTIALS`	ADC 命令返回的凭据文件绝对路径
`GOOGLE_PROJECT_ID`	Google Cloud Project ID
`GOOGLE_ADS_DEVELOPER_TOKEN`	Google Ads Developer Token
`GOOGLE_ADS_LOGIN_CUSTOMER_ID`	可选；通过 Manager Account 访问时填写不含连字符的经理账户 ID

如果界面允许设置启动超时，将其设为 120 秒。第一次启动时 pipx 需要从官方 GitHub 仓库下载服务和依赖。
保存并点击 Restart。

如果界面没有分开的参数或环境变量输入框，可以编辑全局 ~/.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"
# 仅在通过 Manager Account 访问客户账户时取消下一行注释：
# GOOGLE_ADS_LOGIN_CUSTOMER_ID = "YOUR_MANAGER_CUSTOMER_ID"

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

第 5 步：确认 MCP 已连接

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

/mcp

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

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

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

复制下面的 Prompt：

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

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

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

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

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

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

请仅使用 Google Ads MCP 的只读搜索工具分析 Customer 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 条要点指出值得人工复核的变化，但不要执行任何优化。

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

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

目标 Customer 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 Console，确认当前项目与 GOOGLE_PROJECT_ID 完全一致，并在该项目中启用 Google Ads API。启用后等待几分钟再试。

提示 Developer Token 只能访问测试账户

Token 当前只有 Test Account Access。改用测试账户完成验证，或在 API Center 申请 Explorer、Basic 或 Standard Access；修改 Customer ID 无法绕过这个限制。

提示 USER_PERMISSION_DENIED 或账户列表为空

确认 ADC 登录使用的 Google 用户可以在浏览器中打开该 Google Ads 账户。OAuth Client、Developer Token 和 Google Ads 用户权限是三个不同层级，拥有 Token 不代表自动拥有客户账户访问权。

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

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

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

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

凭据与执行安全

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

官方参考资料

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