Google Ads MCP 服务器

此仓库包含运行 MCP 服务器的源代码，该服务器可与 Google Ads API 进行交互。

工具

该服务器使用 Google Ads API 提供多个 工具 和 资源，供 LLM 和 AI 智能体使用。

可用工具

• search：检索关于 Google Ads 账户的信息。

• get_resource_metadata：检索关于 Google Ads API 资源类型（例如 campaign）的元数据。这有助于了解数据的结构以及哪些字段可用于查询。

• list_accessible_customers：返回调用认证用户可直接访问的客户 ID。

配置和命名空间工具

Google Ads MCP 服务器使用 tools_config.yaml 让您有选择地启用或禁用单个工具或工具类别（命名空间），并自定义其命名空间前缀。

一个启用了所有工具的默认 tools_config.yaml 已随包一起捆绑，因此服务器无需额外设置即可直接使用。要自定义您的安装，服务器按以下顺序解析配置：

1. 通过 GOOGLE_ADS_MCP_TOOLS_CONFIG 环境变量设置的显式路径。

2. 当前工作目录中的 tools_config.yaml 文件。

3. 随包捆绑的默认 tools_config.yaml。

如果显式请求的配置文件（通过环境变量）丢失，或任何已解析的文件无效，服务器将引发错误并无法启动。

配置示例：

namespaces:
  # Option 1: Enable category 'customers' with default prefix -> "customers_list_accessible_customers"
  customers: true

  # Option 2: Enable category 'search' with a custom prefix -> "query_search"
  search: "query"

  # Option 3: Fine-grained control over tools in a category
  metadata:
    enabled: true
    prefix: "metadata"
    enabled_tools:
      - get_resource_metadata: true

可用资源

• discovery-document：检索 Google Ads API 发现文档。提供最新版本 Google Ads API 的发现文档，该文档描述了 API 的表面，包括资源、方法和模式。主机 LLM 应访问此资源以了解 Google Ads API 的结构并发现可用功能。

• metrics：检索关于 Google Ads API 中可用于报告的指标的信息。

• segments：检索关于 Google Ads API 中可用于报告的细分的信息。

• release-notes：检索最新版本 Google Ads API 的发布说明。

Related MCP server: gads

说明

1. MCP 服务器会将您的数据暴露给您连接到的智能体或 LLM。

2. 如果您遇到技术问题，请使用 GitHub 问题跟踪器。

3. 为帮助我们收集使用数据，您会注意到您的 API 调用中添加了一个额外的标头：这些数据用于改进产品。

设置说明

设置包括以下步骤：

1. 配置 Python。

2. 配置开发者令牌。

3. 在您的项目中启用 API。

4. 配置凭据。

5. 配置您的 MCP 客户端。

配置 Python

安装 pipx。

配置开发者令牌

按照获取开发者令牌的说明进行操作。

您的开发者令牌必须至少具有浏览者访问权限才能查询生产账户。新令牌可能自动升级为浏览者访问权限；如果没有，您可以通过 API 中心申请。有关详细信息，请参阅访问级别文档。

如果您看到错误*“开发者令牌仅被批准用于测试账户”*，则您的令牌尚未获得生产账户的访问权限。有关如何申请所需访问级别的信息，请参阅访问级别文档。

在您的项目中启用 API

按照说明在您的 Google Cloud 项目中启用以下 API：

• Google Ads API

配置凭据

选项 1：使用 FastMCP OAuth 代理

该服务器支持 FastMCP 的 OAuth 代理 功能，用于动态用户认证。这在将服务器作为 Web 服务运行时非常有用。

要启用它，请设置以下环境变量：

• GOOGLE_ADS_MCP_OAUTH_CLIENT_ID：您的 Google Cloud OAuth 2.0 客户端 ID。

• GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET：您的 Google Cloud OAuth 2.0 客户端密钥。

• GOOGLE_ADS_MCP_BASE_URL：（可选）服务器可访问的基础 URL（默认为 http://localhost:8080）。

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY：（可选）用于跨多个服务器实例或部署签署 FastMCP JWT 令牌的密钥。

• GOOGLE_ADS_MCP_STORAGE_TYPE：（可选）OAuth 状态的存储后端（filetree、redis、firestore 或 memory）。

• GOOGLE_ADS_MCP_STORAGE_PATH：（可选）filetree 持久存储的目录路径。

• GOOGLE_ADS_MCP_STORAGE_REDIS_URL：（可选）用于 redis 持久存储的 Redis URL。

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_PROJECT：（可选）用于 firestore 持久存储的 Google Cloud 项目。默认为从应用程序默认凭据推断出的项目。设置它将选择 firestore 后端，即使 GOOGLE_ADS_MCP_STORAGE_TYPE 未设置。

• GOOGLE_ADS_MCP_STORAGE_FIRESTORE_DATABASE：（可选）用于 firestore 持久存储的 Firestore 数据库名称。默认为 (default)。

• GOOGLE_ADS_MCP_STORAGE_ENCRYPTION_KEY：（可选）用于存储的 OAuth 令牌的加密密钥。

• GOOGLE_ADS_MCP_STORAGE_DISABLE_ENCRYPTION：（可选）设置为 true 以禁用令牌加密。

redis 和 firestore 后端需要与服务器一起安装其存储库：分别运行 pip install py-key-value-aio[redis] 和 pip install google-ads-mcp[firestore]。

一旦启用此功能，您就可以通过您的 MCP 客户端向 API 进行身份验证。

当设置了这些变量时，服务器会自动切换到 streamable-http 传输（SSE/HTTP），而不是 stdio。

您需要将服务器作为单独的进程运行，并配置您的 MCP 客户端以连接到 SSE 端点（例如 http://localhost:8080/mcp）。

选项 2：使用应用程序默认凭据配置凭据

配置您的应用程序默认凭据 (ADC)。确保这些凭据属于可以访问您的 Google Ads 账户或属性的用户。

凭据必须包含 Google Ads API 范围：

https://www.googleapis.com/auth/adwords

查看管理 OAuth 客户端以了解如何创建 OAuth 客户端。

以下是一些您可能会觉得有用的示例 gcloud 命令：

• 使用用户凭据以及 OAuth 桌面或 Web 客户端设置 ADC，前提是已将客户端 JSON 下载到 YOUR_CLIENT_JSON_FILE。

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

• 使用服务账号模拟设置 ADC。

  gcloud auth application-default login \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

当 gcloud auth application-default 命令完成后，复制打印到控制台的 PATH_TO_CREDENTIALS_JSON 文件位置（在以下消息中）。您将在后续步骤中用到它！

Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]

选项 3：使用 Google Ads API Python 客户端库配置凭据。

按照说明设置并配置 Google Ads API Python 客户端库。

如果您已经完成此操作并拥有一个有效的 google-ads.yaml，您可以重用此文件！

在 utils.py 文件中，将 get_googleads_client() 改为使用 load_from_storage() 方法。

配置您的 MCP 客户端

将服务器添加到您的 MCP 客户端配置中。以下是流行客户端的示例。

Antigravity CLI / Antigravity Code Assist

1. 安装 Antigravity CLI 或 Antigravity Code Assist。

2. 配置您的服务器。有关设置 MCP 服务器的详细信息，请参阅 https://antigravity.google/docs/mcp 上的文档。

• 选项 1：使用 FastMCP OAuth 代理（可流式传输 HTTP）

  您可以将服务器作为单独的进程运行，并配置您的 MCP 客户端以连接到 SSE 端点（例如 http://localhost:8080/mcp）。 这也允许使用 FastMCP 的 OAuth 代理 功能进行动态用户认证。

  {
    "mcpServers": {
      "google-ads-mcp": {
        "httpUrl":"http://localhost:8080/mcp",
        "env": {
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"                        
        }
      }
    }
  }

• 选项 2：应用程序默认凭据方法

  将 PATH_TO_CREDENTIALS_JSON 替换为您在上一步中复制到的路径。

  我们还建议您将 GOOGLE_CLOUD_PROJECT 属性添加到 env 对象中。将以下示例中的 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目的项目 ID。

  {
    "mcpServers": {
      "google-ads-mcp": {
        "command": "pipx",
        "args": [
          "run",
          "--spec",
          "git+https://github.com/googleads/google-ads-mcp.git",
          "google-ads-mcp"
        ],
        "env": {
          "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
          "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
        }
      }
    }
  }

• 选项 3：Python 客户端库方法

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

登录客户 ID

如果您通过经理账户访问客户账户，则需要将经理账户的客户 ID 添加到设置文件中。

详见此处。

最终文件将如下所示：

{
  "mcpServers": {
    "google-ads-mcp": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
      }
    }
  }
}

其他 MCP 客户端（Claude Code、Cursor、VS Code 等）

mcpServers 块格式在所有 MCP 客户端中是相同的。将上面显示的配置添加到您的客户端相应的设置文件中（例如，Claude Code 为 ~/.claude/settings.json，Cursor 为 .cursor/mcp.json，带有 Copilot 的 VS Code 为 .vscode/mcp.json）。

部署到 Google Cloud Platform

您可以将此 MCP 服务器托管在 Google Cloud Run 或任何其他基于云的基础设施上，而不是本地托管。如果您想在不同的智能体之间共享服务器，或将其作为 Web 服务运行，这将非常有用。

请注意，此部署方式仅支持通过 OAuth 代理使用 OAuth 客户端 ID 和客户端密钥对进行身份验证（上面的选项 #1）。

前提条件

1. 一个 Google Cloud 项目。

2. 已安装并认证 gcloud CLI，并已设置活动项目。

   gcloud config set project YOUR_PROJECT_ID

第 1 步：构建并推送 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 .

   将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。

第 2 步：部署到 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 服务器可访问的基础 URL：首次部署后，Google Cloud Run 会自动分配此 URL。您可以在部署后更新环境变量。

• GOOGLE_ADS_MCP_JWT_SIGNING_KEY：（生产环境推荐）跨 Cloud Run 实例的持久化 JWT 签名密钥。

• GOOGLE_ADS_MCP_STORAGE_TYPE：（生产环境推荐）用于跨实例持久化 OAuth 令牌的存储后端。设置为 firestore 可使用 Firestore（通过应用默认凭据，无需 VPC 连接器），或设置为 redis 并同时设置 GOOGLE_ADS_MCP_STORAGE_REDIS_URL。

  使用 firestore 需要三件事：构建包含额外依赖的镜像（将 Dockerfile 改为 uv pip install --system .[firestore]），在项目中创建一个 Firestore 数据库（因为不会自动预配），以及为 Cloud Run 服务账号授予 roles/datastore.user 角色。请注意，条目不会自动过期：存储后端在读取时会过滤过期条目，但不会删除它们，并且 expires_at 以字符串形式写入，因此 Firestore 的 TTL 策略也无法收集它们。对于长期运行的部署，请计划定期清理任务。Redis 会自动过期条目。

• 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,GOOGLE_ADS_MCP_JWT_SIGNING_KEY=YOUR_JWT_SIGNING_KEY,GOOGLE_ADS_MCP_STORAGE_TYPE=firestore,FASTMCP_HOST=0.0.0.0"

步骤 3：配置 MCP 客户端

部署完成后，更新您的 MCP 客户端配置（请参阅 https://antigravity.google/docs/mcp 的文档）以使用 Cloud Run URL。

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

试用

启动您的 MCP 客户端。您应该会在可用服务器列表中看到 google-ads-mcp。

以下是一些入门示例提示：

• 询问服务器能做什么：

  what can the 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?

关于客户 ID 的说明

您的代理在大多数提示中都需要并询问客户 ID。如果您在多个客户之间切换，在提示中包含客户 ID 可能会更简单。

How many active campaigns do I have for customer id 1234567890

贡献

欢迎贡献！请参阅贡献指南。