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

Model Context Protocol (MCP) 是一种开放标准，可让大语言模型 (LLM) 安全地与外部数据和应用进行交互。Google Ads MCP 服务器提供了一个连接到 Google Ads API 的标准化桥梁。它让 AI 智能体能够使用自然语言检索和分析账号数据、创建素材资源、上传视频以及管理标签。

社区资源和支持

技术概览

集成 Google Ads MCP 服务器后，您无需再编写自定义代码来处理 Google Ads API 身份验证、资源提取、数据解析以及支持的素材资源或标签变更。服务器会公开可调用的工具和参考资源（请参阅核心功能），LLM 可以检查和调用这些工具和资源。

主要规范

  • 协议：MCP (Model Context Protocol)
  • 模式：读取和部分更改（资产创建、视频上传和标签管理，采用提议和确认验证或可配置的只读模式）
  • 语言：Python 3.10 或更高版本
  • 传输：标准输入/输出 (stdio) 或可流式 HTTP（Cloud Run 上的 streamable-http）
  • 身份验证：本地 stdio 的应用默认凭证（OAuth 2.0 用户凭证或服务账号），或远程 HTTP 的 OAuth 2.0 Web 应用凭证

互动循环的工作原理

  1. 请求：您提交提示，例如“我的广告系列本周的效果如何？”或“为我们的夏季促销活动制作宣传信息素材资源”。
  2. 发现：LLM 检查其可用工具和资源，并选择匹配的 google-ads-mcp 工具。
  3. 执行或试运行验证：读取工具会直接查询 Google Ads API。Mutate 工具首先在建议模式 (validate_only=True) 下运行，以验证输入而不提交更改（请参阅“建议并确认”安全工作流）。
  4. 上下文注入：MCP 服务器将结构化查询结果或建议的 change_items 条目和验证 checksum 摘要返回到 LLM 的上下文窗口。
  5. 回答和确认：LLM 会给出回答，或要求您确认建议的更改。您批准后，LLM 会再次使用 validate_only=False 和匹配的 checksum 值调用 mutate 工具，以提交更改。

开始使用

请按照以下步骤在本地配置和运行 Google Ads MCP 服务器。如需改为部署共享远程服务，请参阅在 Google Cloud 上部署。

前提条件

在配置服务器之前，请在本地环境和 Google Cloud 控制台中完成以下前提条件：

  • Google Cloud 项目：创建或选择已启用 Google Ads API 的 Google Cloud 项目。启用该 API 后，您将获得测试访问权限，可针对测试账号测试读取和更改工作流。如需访问生产账号，请查看 Google Ads API 概览页面，了解探索者、基本或标准访问权限，或申请其中一种访问权限级别。否则，生产调用会失败并显示 AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION 错误。Google 将于 2026 年 9 月 9 日停用开发者令牌 (GOOGLE_ADS_DEVELOPER_TOKEN)。拥有 OAuth 客户端或服务账号的 Google Cloud 项目决定了您的 API 访问权限级别。
  • 凭证：本地 stdio 模式使用 OAuth 2.0 客户端密钥 JSON 文件或您的云项目中的服务账号中的应用默认凭证 (ADC) 进行身份验证。在需要指定默认配额或 ADC 项目时，设置 GOOGLE_CLOUD_PROJECT 环境变量。远程 streamable-http 部署则需要 OAuth 2.0 Web 应用客户端 ID 和客户端密钥（请参阅部署到 Google Cloud Run）。
  • 本地软件（适用于 stdio 模式）：安装 Python 3.10 或更高版本、pipx 以及 gcloud 命令行工具（用于生成用户 ADC 文件）。

配置

  1. 使用已启用 API 的 Google Cloud 项目中的 OAuth 客户端生成应用默认凭证 (ADC)，并添加 Google Ads API 范围：

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

    替换以下内容：

    • PATH_TO_CLIENT_SECRET_JSON：OAuth 2.0 客户端密钥 JSON 文件的路径。

    此命令会输出 Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]（例如 Linux 和 macOS 上的 ~/.config/gcloud/application_default_credentials.json）。如需改为使用服务账号进行身份验证，请跳过此步骤，并将 GOOGLE_APPLICATION_CREDENTIALS 指向服务账号密钥 JSON 文件，或将 --impersonate-service-account 传递给 gcloud auth application-default login。

  2. 将服务器添加到主机的 MCP 配置文件（例如 ~/.gemini/config/mcp_config.json、~/.gemini/settings.json 或 ~/.claude/settings.json）中：

    {
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "google-ads-mcp==0.0.6",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "PROJECT_ID",
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON"
      }
    }
  }
}

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目 ID。
    • PATH_TO_CREDENTIALS_JSON：第 1 步中输出的 ADC JSON 文件的路径，或服务账号密钥 JSON 文件的路径。使用默认 gcloud ADC 文件位置时，您可以省略 GOOGLE_APPLICATION_CREDENTIALS。

    如需通过经理账号访问客户账号，请在 env 中设置 GOOGLE_ADS_LOGIN_CUSTOMER_ID（10 位数字，不带连字符），或在各个工具调用中传递 login_customer_id 参数。

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

借助 Google Ads MCP 服务器，您的 AI 客户端可以实时访问账号报告数据，并使用素材资源制作、视频上传和标签管理工具。将 MCP 服务器与以下配套工具搭配使用，可帮助智能体构建有效的 Google Ads 查询语言 (GAQL) 查询，并诊断账号效果变化。这些工具还会生成客户端库代码，例如用于将创建的素材资源关联到广告系列或执行其他不受支持的更改的脚本：

  • 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 验证、客户端库代码生成和线下转化问题排查功能。阅读什么是 Google Ads API 开发者助理？或按照安装指南操作。

核心功能

以下部分介绍了服务器的读取工具、部分变更工具和参考资源。从 v0.0.6 开始，工具默认使用其类别命名空间前缀（例如 search_search）进行注册。从无前缀版本升级提示或许可清单时，请更新工具名称或在 tools_config.yaml 中设置空前缀 ("")（请参阅配置工具命名空间和只读模式）。

朗读工具

  • customers_list_accessible_customers（工具 list_accessible_customers）：返回经过身份验证的用户可直接访问的 Google Ads 客户 ID。
  • search_search（工具 search）：根据结构化参数（customer_id、resource 和 fields，以及可选的 conditions、orderings、limit 和 login_customer_id）而非原始 GAQL 字符串构建并运行 GAQL SearchStream 查询。每个查询都会附加 PARAMETERS omit_unselected_resource_names=true，以干净利落地提取资源属性、指标、细分、预算和状态。
  • metadata_get_resource_metadata（工具 get_resource_metadata）：检索 Google Ads API 资源类型（例如 "campaign"）的可选、可过滤和可排序属性、指标和细分。在调用 search_search 工具之前，请使用此元数据发现有效的查询字段，包括在次要版本（例如 v26.2）中添加的指标和细分。

更改工具（部分支持）

  • assets_create_asset（工具 create_asset）：创建独立的 Google Ads 素材资源，并为 TEXT、IMAGE、YOUTUBE_VIDEO、SITELINK、CALLOUT 和 STRUCTURED_SNIPPET 素材资源类型提供专用参数。为其他可变 AssetService 类型（例如 PRICE、PROMOTION、CALL 或 BUSINESS_MESSAGE）传递 extra_params 字典，并为 SITELINK 资源添加根级 final_urls 以及 sitelink_link_text。本地文件路径 (image_asset_path) 仅在本地 stdio 模式下有效。对于远程 HTTP 部署，请传递 base64 编码的 image_asset_data 参数，并将 image_asset_mime_type 设置为 IMAGE_PNG、IMAGE_JPEG 或 IMAGE_GIF（最大 20 MB）。
  • assets_upload_video_asset（工具 upload_video_asset）：仅在本地 stdio 模式下，通过 Google Ads API 将本地视频文件（.3gp、.avi、.flv、.mkv、.mov、.mp4、.mpeg、.mpg、.ogg、.webm 或 .wmv）上传到 YouTube。video_title 和 video_description 都是必需参数，隐私设置默认为 UNLISTED（或在具有用户 OAuth 的广告客户拥有的品牌频道上默认为 PUBLIC）。此工具会返回 Google Ads video_upload_id 值（和资源名称），而不是 11 个字符的 YouTube video_id。使用 search_search 工具（按 you_tube_video_upload.video_upload_id 过滤）查询 you_tube_video_upload，直到 you_tube_video_upload.state = 'PROCESSED'。然后，将 you_tube_video_upload.video_id 作为 youtube_video_id 参数传递给 assets_create_asset (asset_type="YOUTUBE_VIDEO")。
  • labels_manage_labels（工具 manage_labels）：创建、更新和移除账号标签，包括名称、说明和十六进制背景颜色。
  • labels_manage_label_associations（工具 manage_label_associations）：支持对 CAMPAIGN、CUSTOMER、AD_GROUP 和 AD_GROUP_CRITERION 资源执行 CREATE 和 REMOVE 标签关联操作（不支持 UPDATE）。对于 CUSTOMER 资源，resource_id 是可选的，默认值为 customer_id。为 AD_GROUP_CRITERION 资源传递复合 {ad_group_id}~{criterion_id} ID，并通过传递 resource_id 和 label_id 或 association_resource_name 来移除关联。不支持广告级 AD_GROUP_AD 标签。

参考资源

无论 tools_config.yaml 设置如何，服务器都会公开四个保持装载状态的只读 MCP 资源：

  • resource://discovery-document：Google Ads API 资源、服务方法和架构的 JSON REST 发现概览。它与 metadata_get_resource_metadata 工具相辅相成，后者会返回可选择、可过滤和可排序的 GAQL 查询字段。
  • resource://metrics：Google Ads API 指标的 HTML 参考文档。
  • resource://segments：Google Ads API 细分的 HTML 参考文档。
  • resource://release-notes：HTML Google Ads API 版本说明，涵盖版本变更和新功能。

“提议并确认”安全工作流程

每个变更工具（assets_create_asset、assets_upload_video_asset、labels_manage_labels 和 labels_manage_label_associations）都会强制执行两步式提议和确认工作流，以帮助防止意外修改账号：

  1. Propose（validate_only=True，默认）：验证输入，但不提交更改。素材资源和标签工具会执行实时 Google Ads API validate_only 试运行。由于 YouTubeVideoUploadService 没有试运行模式，因此 assets_upload_video_asset 会改为验证本地文件并绑定其大小和修改时间戳。每个工具都会返回人类可读的 change_items 条目，以及绑定到 customer_id 参数和请求载荷的无状态 SHA-256 checksum 摘要。
  2. 确认 (validate_only=False)：在显示 change_items 列表并收到您的批准后，智能体会再次调用该工具，并传入 validate_only=False、相同的 customer_id 参数和实参，以及第 1 步中的 checksum 值。在更改账号之前，服务器会拒绝任何缺失或不匹配的校验和。

配置工具命名空间和只读模式

服务器捆绑了一个默认 tools_config.yaml 文件，其中启用了所有五个工具类别（customers、search、metadata、labels 和 assets）。自定义 tools_config.yaml，以选择性地启用或停用单个工具或命名空间、更改或移除命名空间前缀，或强制执行严格只读部署。

启动时，服务器会按以下顺序解析 tools_config.yaml：

  1. GOOGLE_ADS_MCP_TOOLS_CONFIG 环境变量中的显式路径（建议用于本地 stdio 主机，其工作目录可能与项目文件夹不同）。
  2. 服务器当前工作目录中的 tools_config.yaml 文件。
  3. 与软件包捆绑在一起的默认 tools_config.yaml 文件。

如果 GOOGLE_ADS_MCP_TOOLS_CONFIG 指向缺失的文件，或者任何已解析的配置文件无效，服务器会在启动时引发错误，而不是回退到默认值。

以下最小 tools_config.yaml 文件强制执行严格的只读部署：

namespaces:
  customers: true
  search: true
  metadata: true
  labels: false
  assets: false

以下 tools_config.yaml 文件可自定义前缀并过滤单个工具（例如，在 Cloud Run 上公开 base64 create_asset 工具，同时停用仅限本地的 upload_video_asset 工具）：

namespaces:
  # Default prefix ("customers_list_accessible_customers")
  customers: true

  # Empty prefix mounts unprefixed tool names ("search")
  search: ""

  # Custom prefix ("schema_get_resource_metadata")
  metadata: "schema"

  # Enable only specific tools in a multi-tool category
  assets:
    enabled_tools:
      - create_asset

提示示例

连接服务器后，在 MCP 客户端中尝试以下提示。

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

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

创建资产、上传视频和管理标签

Create a callout asset with the text "Free Shipping" for account 1234567890

Upload /path/to/promo.mp4 with title "Summer Sale" and description "Summer promo video" for account 1234567890

Create a label named "Q4 Promo" with background color #34A853 and apply it to campaign 9876543210 in account 1234567890

在 Google Cloud 上部署

如需在多个代理之间共享 MCP 服务器或将其作为 Web 服务运行，请将其托管在 Google Cloud Run 或其他云基础设施提供商上，而不是在本地运行。

前提条件

  1. 一个已启用 Google Ads API 的 Google Cloud 项目（如需了解正式版访问权限要求，请参阅前提条件）。

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

    gcloud config set project PROJECT_ID

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目 ID。

构建和推送 Docker 映像

使用 Cloud Build 构建容器映像并将其推送到 Artifact Registry，而无需在本地安装 Docker：

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

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

  2. 从 GitHub 代码库中的发布标记（或从本地签出中的 .，如果您自定义了 Dockerfile 或 tools_config.yaml）构建并提交映像：

    gcloud builds submit https://github.com/googleads/google-ads-mcp \
  --git-source-revision=v0.0.6 \
  --tag=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目 ID。

    每当您更新 google-ads-mcp 或升级捆绑的 google-ads Python 客户端库以支持新的 Google Ads API 版本（例如 v26.2）时，请重新构建并重新部署映像。

部署到 Google Cloud Run

为 Cloud Run 服务配置以下环境变量和 Secret：

  • GOOGLE_ADS_MCP_OAUTH_CLIENT_ID：来自已启用 API 的 Google Cloud 云项目的 OAuth 2.0 Web 应用客户端 ID，用于应用级 OAuth 身份验证。完成以下 OAuth 配置步骤：
    • 为您计划连接的所有 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）。Cloud Run 会在初始部署期间分配此网址，因此请先在不使用此变量的情况下进行部署，然后再更新服务。
  • GOOGLE_ADS_MCP_JWT_SIGNING_KEY（推荐用于多实例 Cloud Run）：一个永久性 Secret，用于在容器重启和横向扩缩期间为 FastMCP JWT 签名。
  • GOOGLE_ADS_MCP_STORAGE_TYPE（推荐用于多实例 Cloud Run）：用于 OAuth 客户端注册和令牌的永久性后端（redis 搭配 GOOGLE_ADS_MCP_STORAGE_REDIS_URL 或 firestore）。由于库存 v0.0.6 Dockerfile 仅安装内存中后端，因此请先在自定义 Dockerfile 中安装 py-key-value-aio[redis] 或 .[firestore]。使用 firestore 还需要 Firestore 数据库和 Cloud Run 服务账号上的 roles/datastore.user IAM 角色。对于使用内存中存储空间的单实例测试，请传递 --max-instances=1。
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID（可选）：当工具调用省略 login_customer_id 参数时，使用的默认 10 位数经理客户 ID（不带连字符）。
  • GOOGLE_ADS_MCP_TOOLS_CONFIG（可选）：自定义 tools_config.yaml 文件的容器路径（例如，从 Secret Manager 装载到 /etc/mcp/tools_config.yaml，以强制执行只读模式，而无需重新构建映像）。请参阅配置工具命名空间和只读模式。

将 GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET 和 GOOGLE_ADS_MCP_JWT_SIGNING_KEY 存储在 Secret Manager 中，并将服务部署到 Google Cloud Run：

gcloud run deploy google-ads-mcp \
  --image=us-central1-docker.pkg.dev/PROJECT_ID/mcp-servers/google-ads-mcp:v0.0.6 \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=CLIENT_ID" \
  --set-secrets="GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=MCP_OAUTH_CLIENT_SECRET:latest,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=MCP_JWT_SIGNING_KEY:latest"

在 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://CLOUD_RUN_SERVICE_URL"

替换以下内容：

  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • CLIENT_ID：您的 OAuth 2.0 Web 应用客户端 ID。
  • MCP_OAUTH_CLIENT_SECRET：存储 OAuth 2.0 客户端密钥的 Secret Manager 密钥名称。
  • MCP_JWT_SIGNING_KEY：存储 JWT 签名密钥的 Secret Manager 密钥名称。
  • CLOUD_RUN_SERVICE_URL：分配给 Cloud Run 服务的主机名（例如 google-ads-mcp-xyz-uc.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 后，服务器会对每个请求强制执行 Google OAuth 2.0，并向未经身份验证的调用方返回 401 Unauthorized HTTP 状态代码。每个工具调用都会在经过身份验证的调用方的 OAuth 身份下执行。
  • 如果省略 --allow-unauthenticated，则调用方必须在每个请求中传递 Google Cloud OIDC 身份令牌。标准 AI 客户端（例如 Claude 和 ChatGPT）使用最终用户 OAuth，而不是 Google Cloud IAM 令牌，因此直接连接需要将 --allow-unauthenticated 与应用级 OAuth 配对。

配置 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）：在客户端的连接器设置中，添加一个自定义连接器，该连接器指向带有 /mcp 路径的服务网址（例如 https://google-ads-mcp-xyz-uc.a.run.app/mcp）。 选择使用 OAuth 客户端 ID 和客户端密钥的 OAuth 2.0 身份验证，并确认客户端的回调 URI 位于 OAuth 客户端的已获授权的重定向 URI 中。
  • 不支持 OAuth 的客户端：不支持 HTTP OAuth 流程的客户端会收到 401 Unauthorized HTTP 状态代码。对于这些客户端，请改用本地 stdio 配置。

以下示例在 ~/.gemini/settings.json 中配置 gemini 命令行工具（对于 ~/.gemini/config/mcp_config.json 中的 Google Antigravity，请将 "httpUrl" 替换为 "serverUrl" 或 "url"）：

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://CLOUD_RUN_SERVICE_URL/mcp"
    }
  }
}

替换以下内容：

  • CLOUD_RUN_SERVICE_URL：分配给 Cloud Run 服务的主机名（例如 google-ads-mcp-xyz-uc.a.run.app）。

后续步骤