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

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

社区资源和支持

技术概览

通过实现此 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 概览页面，确保您的项目具有 Explorer 访问权限、基本访问权限或标准访问权限级别。如果没有， 请申请其中一个访问权限级别。请注意， 开发者令牌 (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 Cloud 上部署

您可以将此 MCP 服务器托管在 Google Cloud Run 或任何其他基于云的基础架构上，而不是在本地托管。如果您想在不同的智能体之间共享服务器，或者将其作为 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 2.0 客户端 ID（在 Google Cloud 项目中配置为网络应用 ），用于应用级 OAuth 身份验证。确保：
    • 您已为计划连接的任何 AI 客户端添加适当的已获授权的重定向 URI（例如 https://claude.ai/api/mcp/auth_callback、https://chatgpt.com/connector_platform_oauth_redirect 或 https://antigravity.google/oauth-callback）。
    • 您已将 https://www.googleapis.com/auth/adwords 范围添加到 OAuth 权限请求页面，具体路径为“API 和服务”>“OAuth 权限请求页面”>“数据访问权限” （添加或移除范围 ）。
    • 如果您的 OAuth 权限请求页面发布状态设置为测试 （默认），您已将连接到 MCP 服务器的 Google 账号添加为测试用户，具体路径为“API 和服务”>“OAuth 权限请求页面”>“受众群体”（测试用户 > + 添加用户）。
  • 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。

配置 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 Unauthorized 响应。对于这些工具，请改用 本地 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：执行 Google Ads 查询语言 (GAQL) 请求，以提取资源指标、预算和状态。

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

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

开始使用的示例提示

询问服务器可以做什么：

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