Google Ads MCP 服务器：开发者集成指南

Model Context Protocol (MCP) 是一种开放标准，可让大语言模型 (LLM) 安全地与外部数据和应用进行交互。Google Ads MCP 服务器提供了一个连接到 Google Ads API 的标准化桥梁，让 AI 智能体能够使用自然语言分析和检索广告系列数据。

社区资源和支持

• GitHub 代码库：在 google-ads-mcp 代码库中查找演示和示例，以及报告 bug 或建议功能。

  使用“Issues”标签页报告 bug 和功能请求。

• 社区：加入 Google 广告社区 Discord 上的 #ads-api-ai-tools 频道。

技术概览

通过实现此 MCP 服务器，您无需再编写自定义“粘合代码”来执行 Google Ads API 身份验证、资源提取和数据解析。服务器会公开 LLM 可以自主发现和调用的特定工具。

主要规范

• 协议：MCP (Model Context Protocol)
• 模式： 只读（当前版本）
• 语言：Python
• 传输：标准输入/输出 (stdio) 或可流式 HTTP (streamable-http / Cloud Run)
• 身份验证：OAuth 2.0 或服务账号

互动循环的工作原理

1. 请求：用户提交查询，例如“我的广告系列本周效果如何？”。
2. 发现：LLM 检查其可用工具，并识别 google-ads-mcp 搜索功能。
3. 执行：MCP 服务器执行底层 Python 逻辑，以查询 Google Ads API。
4. 上下文注入：结构化结果会返回到 LLM 的上下文窗口。
5. 回答：LLM 将数据合成为人类可读的回答。

开始使用

请按照以下步骤配置和使用 Google Ads MCP 服务器。

前提条件

在配置之前，请确保您拥有 Google Cloud 控制台中的以下凭据：

• 项目 ID：您的 Google Cloud 项目 ID (GOOGLE_PROJECT_ID)。请查看 Google Ads API 概览页面，确保您的项目具有探索者访问权限、基本访问权限或标准访问权限级别。如果没有，请申请其中一个访问权限级别。请注意，开发者令牌 (GOOGLE_ADS_DEVELOPER_TOKEN) 已于 2026 年 9 月 9 日停用，并且最新版本的 Google Ads MCP 服务器不再需要开发者令牌，因为 API 访问权限级别与 Google Cloud 项目相关联。
• OAuth 凭证：OAuth 2.0 客户端 ID/客户端密钥对，或一组应用默认凭证。

配置

如需将服务器集成到与 MCP 兼容的主机中，请将以下条目添加到主机的 MCP 配置文件（例如 settings.json）中，并将 GOOGLE_APPLICATION_CREDENTIALS 指向您的 ADC JSON 文件（或使用 gcloud auth application-default login 配置默认 ADC）。如果您通过普通管理者账号访问账号，还可以设置 GOOGLE_ADS_LOGIN_CUSTOMER_ID。 请参阅托管服务商的文档，了解此配置的确切位置和文件名。

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

可选：为智能体配备技能和开发者助理

Google Ads MCP 服务器可让您的 AI 客户端对实时账号数据拥有只读权限。为了帮助您的智能体构建有效的 Google Ads 查询语言 (GAQL) 查询、诊断账号效果变化并生成客户端库代码，请将 MCP 服务器与以下配套工具搭配使用：

• Google Ads API 智能体技能：Google Ads API 专用指令和工作流的可移植模块，包括 google-ads-api-mcp-setup、google-ads-api-account-diagnostics 和 google-ads-api-quickstart，可指导智能体如何以更低的 token 开销高效使用 Google Ads MCP 服务器。您可以使用单个命令安装它们（需要 Node.js），也可以参阅 Google Ads API 智能体技能指南，了解 Antigravity、Claude Code、Codex 和 Cursor 选项：

  npx skills add google/skills/skills/ads
  

• Google Ads API Developer Assistant：一款适用于 Google Antigravity 和 Claude Code 的模块化插件，可提供本地 Protobuf 架构检查、程序化 GAQL 验证、客户端库代码生成（包括 mutate 脚本）以及线下转化问题排查。如需了解其运作方式，请参阅什么是 Google Ads API 开发者助理？或按照安装指南操作。

在 Google Cloud 上部署

您可以在 Google Cloud Run 或任何其他基于云的基础设施上托管此 MCP 服务器，而不是在本地托管。如果您想在不同的代理之间共享服务器或将其作为 Web 服务运行，此功能会很有用。

前提条件

1. Google Cloud 项目

2. 已安装 gcloud 命令行工具，已通过身份验证，并配置了活跃项目：

   gcloud config set project YOUR_PROJECT_ID
   

构建和推送 Docker 映像

您可以使用 Cloud Build 构建映像并将其推送到 Artifact Registry，而无需在本地安装 Docker。

1. 在 Artifact Registry 中创建代码库：

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

2. 转到项目目录：

   cd <full path>/google-ads-mcp
   

3. 构建并提交映像：

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

   请注意，每当您想要将已部署的服务器更新到最新版本时，都必须执行此步骤。

部署到 Google Cloud Run

请务必设置所需的环境变量：

• GOOGLE_PROJECT_ID：您的 Google Cloud 云项目 ID，该项目具有适当的 API 访问权限级别。
• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID：用于应用级 OAuth 身份验证的 OAuth 2.0 客户端 ID（在 Google Cloud 项目中配置为 Web 应用）。确保：
  • 您已为计划连接的所有 AI 客户端（例如 https://claude.ai/api/mcp/auth_callback、https://chatgpt.com/connector_platform_oauth_redirect 或 https://antigravity.google/oauth-callback）添加了适当的已获授权的重定向 URI。
  • 您已在 API 和服务 > OAuth 权限请求页面 > 数据访问（添加或移除范围）下，将 https://www.googleapis.com/auth/adwords 范围添加到 OAuth 权限请求页面。
  • 如果您的 OAuth 权限请求页面发布状态设置为测试（默认），您已在 API 和服务 > OAuth 权限请求页面 > 受众群体（测试用户 > + 添加用户）下将连接到 MCP 服务器的 Google 账号添加为测试用户。
• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET：与 OAuth 客户端 ID 对应的 OAuth 客户端密钥。
• GOOGLE_ADS_MCP_BASE_URL：MCP 服务器可访问的公共基础网址（例如 https://google-ads-mcp-xyz-uc.a.run.app）。由于 Google Cloud Run 会在初始部署期间生成此网址，因此请先在不使用此变量的情况下进行部署，然后在部署后更新服务。
• FASTMCP_HOST：将此值设置为 0.0.0.0，以允许 FastMCP 接受来自所有 IP 地址的连接。

将服务部署到 Google Cloud Run：

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_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,FASTMCP_HOST=0.0.0.0"

Cloud Run 完成部署后，检索分配的服务网址，并使用 GOOGLE_ADS_MCP_BASE_URL 环境变量更新服务：

gcloud run services update google-ads-mcp \
  --region us-central1 \
  --update-env-vars="GOOGLE_ADS_MCP_BASE_URL=https://your-cloud-run-url.a.run.app"

身份验证和安全模型

使用 --allow-unauthenticated 进行部署会停用 Cloud Run 的基础设施级 IAM 检查 (roles/run.invoker)，以便外部 AI 客户端无需 Google Cloud 服务账号令牌即可连接。身份验证改为委托给应用层：

• 提供 GOOGLE_ADS_MCP_OAUTH_CLIENT_ID 和 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET 后，MCP 服务器会对所有传入请求强制执行 Google OAuth 2.0，并向未经身份验证的调用方返回 HTTP 401 响应。所有工具请求都严格在经过身份验证的调用方的 OAuth 身份下执行。
• 省略 --allow-unauthenticated 会强制执行 Cloud Run 基础架构 IAM，这要求调用方在每个请求中传递 Google Cloud OIDC 身份令牌。由于标准 AI 客户端（例如 Claude 和 ChatGPT）使用最终用户 OAuth 而非 Google Cloud IAM 身份令牌进行身份验证，因此从这些平台进行直接连接需要使用应用级 OAuth 的 --allow-unauthenticated。

注意： 使用 --allow-unauthenticated 进行部署时，切勿省略 GOOGLE_ADS_MCP_OAUTH_CLIENT_ID 和 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET。这些环境变量会触发服务器从本地 stdio 模式切换到 streamable-http 传输。否则，服务器无法强制执行身份验证，并会回退到应用默认凭证 (ADC)，从而向未经身份验证的调用方公开容器的服务账号凭证。

配置 MCP 客户端

部署后，使用 Cloud Run 网址配置 MCP 客户端。由于服务器需要 OAuth 2.0 身份验证，因此客户端必须支持 MCP OAuth 流程或提供已获授权的不记名令牌：

• 支持 OAuth 的客户端：对于支持 MCP OAuth 发现的客户端（例如 Antigravity），连接到端点会触发身份验证提示，要求使用 Google 账号登录并授予 https://www.googleapis.com/auth/adwords 范围（在 Google Cloud 控制台中列为 .../auth/adwords）。
• 第三方 AI 平台（Claude、ChatGPT）：在客户端的连接器或集成设置中，添加一个指向 Cloud Run 网址且路径为 /mcp 的自定义连接器（例如 https://your-cloud-run-url.a.run.app/mcp），选择 OAuth 2.0 身份验证（使用您自己的 OAuth 客户端 ID 和客户端密钥），并确保将客户端的回调 URI 添加到 OAuth 客户端的已获授权的重定向 URI 中。（托管式端点试点计划的许可清单参与者也可以参阅托管式 MCP 设置指南。）
• 不支持 OAuth 的客户端：不支持 HTTP OAuth 流程的客户端将收到 HTTP 401 未授权响应。对于这些工具，请改用本地 stdio 配置。

支持 OAuth 的客户端（例如 ~/.gemini/settings.json）的配置示例：

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

核心功能（工具）

该服务器公开了专为账号发现和效果报告设计的工具：

• list_accessible_customers：返回经过身份验证的用户可以访问的 Google Ads 客户 ID 和账号名称的列表。
• search：执行 GAQL 请求，以提取资源指标、预算和状态。

• get_resource_metadata：检索 Google Ads API 资源类型（例如 "campaign"）的相关元数据。

  这有助于了解数据的结构以及哪些字段可供查询。

注意： 此实现严格为只读。它无法修改出价、暂停广告系列或创建新素材资源。如需为 mutate 操作生成客户端库代码、在本地验证 GAQL 查询或检查 Protobuf 架构，请使用 Google Ads API 开发者助理。如需获取 MCP 设置和账号诊断工作流方面的指导，请安装 Google Ads API 代理技能。

入门提示示例

询问服务器可以执行的操作：

What can the google-ads-mcp server do?

询问客户情况：

What customers do I have access to?

询问广告系列相关问题：

How many active campaigns do I have?
How is my campaign performance this week?
Give me a report of the top spending campaigns split by device category over the
last 7 days for account 1234567890

后续步骤

• 安装 Google Ads API 代理技能
• 了解 Google Ads API 开发者助理
• 安装并使用 Google Ads API Developer Assistant