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 Ads 开发者控制台中的以下凭据：

配置

如需将服务器集成到与 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_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
      }
    }
  }
}

在 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. 构建并提交映像：

    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。
  • GOOGLE_ADS_DEVELOPER_TOKEN：您希望 MCP 服务器使用的开发者令牌 。
  • 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_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,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