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/SSE (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 MCP 服务器中，不再需要开发者令牌 (GOOGLE_ADS_DEVELOPER_TOKEN)，因为 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：您希望 MCP 服务器使用的 OAuth 客户端 ID。
  • GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET：您希望 MCP 服务器使用的 OAuth 客户端密钥。
  • GOOGLE_ADS_MCP_BASE_URL：MCP 服务器可访问的基本网址；这是在您首次部署后由 Google Cloud Run 自动分配的。您可以在部署后更新环境变量。
  • FASTMCP_HOST：将此值设置为 0.0.0.0 可让 FastMCP 接受来自所有 IP 地址的连接。
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,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

配置 MCP 客户端

部署完成后，更新 MCP 客户端配置（例如 ~/.gemini/settings.json），以使用 Cloud Run 网址。

{
  "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