Google Ads MCP

Google Ads MCP 是一个本地、安全优先、只读的 MCP 服务器和 Codex 插件，用于检查 Google Ads 账户。版本 0.1.0 提供受限资源清单、报告、元数据、变更历史和安全 GAQL 工具。它不包含写入、上传、调度、删除、优化器或托管传输功能。

公开的 Python 发行版名为 google-ads-operator-mcp。产品和命令仍为 Google Ads MCP 和 google-ads-mcp。

安全边界

• 每个账户级请求都同时指定一个配置文件和客户 ID。

• Google 凭据保留在应用默认凭据中，或位于存储库之外、显式仅限所有者的 google-ads.yaml 中。

• accounts.json 只能包含开发者令牌的环境变量名，绝不能包含令牌本身。

• allowWrites 必须为 false；任何其他值都会被拒绝。

• 生产适配器仅构造 GoogleAdsService、CustomerService 和 GoogleAdsFieldService。

• 工具接收的是规范化行，而不是 Google 客户端或原始响应封装。

• MCP 模式将 stdout 保留给 JSON-RPC。诊断信息和脱敏后的失败代码输出到 stderr。

在连接生产账户之前，请阅读 SECURITY.md、PRIVACY.md 和 威胁模型。

Related MCP server: appstoreconnect-codex-mcp

要求

• Python 3.11、3.12 或 3.13

• uv

• 具有开发者令牌的 Google Ads API 访问权限

• ADC，或单独存储的仅限所有者的 google-ads.yaml

请参阅 Google 官方指南，了解开发者令牌、Python 客户端配置和应用默认凭据。

本地设置

uv sync --frozen --all-groups
uv run --frozen google-ads-mcp version
uv run --frozen google-ads-mcp config init

公开发布后，独立 CLI 也可以通过 uv tool install google-ads-operator-mcp==0.1.0 安装。对于最终的干净插件验收门禁，请使用发布插件存档，而不是源代码树副本。

编辑 ~/.config/google-ads-mcp/accounts.json，替换公共账户 ID，然后恢复仅所有者权限：

从本地机密管理器中导出 GOOGLE_ADS_DEVELOPER_TOKEN，不要将其值放入存储库或 shell 历史记录中，然后运行：

chmod 600 ~/.config/google-ads-mcp/accounts.json
gcloud auth application-default login
uv run --frozen google-ads-mcp config validate
uv run --frozen google-ads-mcp auth doctor --profile production-read-only

请勿将开发者令牌、OAuth 刷新令牌、客户端密钥、ADC JSON 或 YAML 内容粘贴到本存储库、issue、终端记录或聊天中。

配置

配置优先级依次为 --config、GOOGLE_ADS_MCP_CONFIG、~/.config/google-ads-mcp/accounts.json。

{
  "profiles": [
    {
      "name": "production-read-only",
      "loginCustomerId": "1234567890",
      "defaultCustomerId": "0987654321",
      "auth": {
        "type": "adc",
        "developerTokenEnv": "GOOGLE_ADS_DEVELOPER_TOKEN"
      },
      "allowWrites": false
    }
  ]
}

对于现有的 Google 客户端 YAML，请使用 {"type":"googleAdsYaml","path":"/absolute/owner-only/google-ads.yaml"}。相对路径和符号链接会被拒绝。服务器绝不会在工作目录或存储库中搜索 YAML 凭据。

CLI

google-ads-mcp version
google-ads-mcp config init
google-ads-mcp config validate
google-ads-mcp auth doctor --profile <name>
google-ads-mcp accounts discover --profile <name>
google-ads-mcp serve --stdio

MCP 工具

v0.1 的固定工具范围如下：

auth_check                customers_list
customer_get              customer_hierarchy
account_health            campaigns_query
campaign_inventory        resource_metadata
reports_catalog           report_run
change_events_query       gaql_validate
gaql_search

类型化列表每页最多返回 200 项。单次 Google 读取上限为 1,000 个规范化行。五分钟游标绑定到配置文件和确切请求，每个配置文件最多 20 个活动游标。安全 GAQL 没有游标，并且要求单个无注释的 SELECT、非敏感资源和 LIMIT 1..1000。

有关参数、证据语义和报告行为，请参阅 docs/tools.md。

Codex 插件

存储库根目录即插件根目录。.mcp.json 调用 ./bin/google-ads-mcp-launcher，后者仅通过 stdio 执行冻结的 uv 环境。隐式 google-ads-operator 技能将所有账户字符串视为不可信数据，并且永远不会提议不可用的变更工具。

该存储库有意不创建或修改个人市场条目。发布存档安装会在验收期间单独验证。

验证

uv run --frozen ruff check .
uv run --frozen pyright
uv run --frozen pytest
uv run --frozen python scripts/validate_read_only.py
uv run --frozen python scripts/validate_gaql_templates.py
uv run --frozen python ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
uv run --frozen python ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/google-ads-operator

自动化验证不等于真实账户验收。在 v0.1.0 之前，docs/acceptance.md 中的测试账户和生产环境只读验收门禁仍然是必需的。

许可证

Apache-2.0。Google Ads 是 Google LLC 的商标。本项目是独立的，未经 Google 认可。