googleads/google-ads-mcp

项目介绍

这是一个 Model Context Protocol 服务器，把 Google Ads API 接入 AI Agent 和 LLM 客户端。模型可以通过工具读取账户数据、了解资源结构、列出可访问客户，并在受控流程下管理标签和广告素材，而不必直接拼 API 请求。

读工具包括 search（用 GAQL 查询账户）、get_resource_metadata 和 list_accessible_customers。写工具包括 create_asset、upload_video_asset、manage_labels 和 manage_label_associations。此外还暴露 discovery document、metrics、segments 和 release notes 等资源，帮助模型先理解 API 结构再查询。

所有写操作都走「Propose & Confirm」两步流程：第一次调用默认 validate_only=True，只做校验并返回变更项和校验和；第二次调用必须带相同参数、相同 customer ID 和该校验和，否则在改动账户前就被拒绝。

快速使用

先准备 Google Cloud 项目，启用 Google Ads API，并获取带 https://www.googleapis.com/auth/adwords 权限的凭据，可选 Application Default Credentials、FastMCP OAuth 代理或已有 google-ads.yaml。

用 pipx 运行服务器，已有发布版本时可固定版本号：

pipx run --spec "google-ads-mcp==X.Y.Z" google-ads-mcp

然后在 MCP 客户端中注册。典型的 stdio 配置指向同一 pipx 命令，并传入凭据路径和项目 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"
      }
    }
  }
}

重启客户端后，可以问「我能访问哪些客户？」或「我有多少活跃广告系列？」。多数提示需要 customer ID，可以直接写在问题里，经理账户也可以通过 GOOGLE_ADS_LOGIN_CUSTOMER_ID 设默认值。

以 Web 服务方式部署时，设置 OAuth 代理相关环境变量后，服务器会从 stdio 切换为 streamable HTTP，端点形如 http://localhost:8080/mcp。Antigravity 客户端要使用 serverUrl 字段，Codex 可以用 codex mcp add google_ads --url http://localhost:8080/mcp 注册。仓库还提供 Dockerfile 和 Quadlet 示例用于 rootless Podman 部署，README 也说明了用 Cloud Run 配合 Firestore 或 Redis 保存 OAuth 状态的流程。

使用约束

默认的 tools_config.yaml 启用全部工具；要严格只读，关闭 labels 和 assets 命名空间即可。自定义配置按 GOOGLE_ADS_MCP_TOOLS_CONFIG、当前目录、包内默认文件的顺序查找；显式指定的文件缺失或格式无效时服务器会直接启动失败。

本地文件相关功能有限制：image_asset_path 和 upload_video_asset 只在本地 stdio 模式下可用，远程 HTTP 部署需改用 base64 的 image_asset_data。连接 Agent 意味着 Google Ads 账户数据会暴露给所连接的模型或客户端；README 还说明 API 调用会附加一个用于收集使用数据的请求头。

Firestore 存储的 OAuth 条目不会自动过期，长期运行需要定期清理；Redis 会自行过期。项目采用 Apache-2.0 许可证。

HotRepo 点评

该项目在 2026-11-11 的 Python 日榜上记录到第 12 名，当日新增 9 Star，当前共 1,149 Star、362 Fork。这只是单次榜单记录，不足以判断长期趋势，但 Fork 与 Star 的比例说明确实有不少人在尝试接入。作为官方发布的广告平台 API 适配层，最实用的设计是写操作的校验和确认流程，以及可以直接切换为只读的配置，适合让 Agent 查看广告数据而不随意改动账户的团队。

项目源码与说明