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)
  • 身份验证：OAuth 2.0 或服务账号

互动循环的运作方式

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

开始使用

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

前提条件

在配置之前，请确保您已从 Google Cloud 控制台获取以下凭据：

配置

如需将服务器集成到 MCP 兼容的主机中，请将以下条目添加到主机的 MCP 配置文件（例如 settings.json）中。请参阅主机提供商的文档，了解此配置的确切位置和文件名。

JSON

{
  "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 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 资源类型（例如“广告系列”）的元数据。

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

入门提示示例

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

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