mcpField
G
google-ads

google-ads

github.com/acedatacloud营销与增长17169 次安装今天更新
代码仓库

关于 google-ads

这款命令行技能使用 curl 和 jq 查询 Google Ads API，可发现账号并通过 GAQL 获取广告系列、广告组、关键词及客户数据。调用需提供 OAuth 和开发者令牌凭据。

主要功能

  1. 01列出可访问的客户账号
  2. 02使用 searchStream 执行 GAQL 报告
  3. 03查询广告系列和广告组数据
  4. 04获取关键词与客户指标
  5. 05处理经理账号调用上下文

适用场景

  1. 01查找 OAuth 用户可访问的账号
  2. 02查看广告系列费用、点击和转化
  3. 03检查广告组及关键词数据
  4. 04在经理账号下运行报告

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/acedatacloud/skills --skill google-ads

安装后在 Claude Code 中输入/google-ads确认已加载。

详细介绍

通过 curl + jq 查询 Google Ads API。需要两个凭据和一个上下文 标头：

  • $GOOGLE_ADS_TOKEN — 用户的 OAuth bearer（adwords scope）→ Authorization: Bearer $GOOGLE_ADS_TOKEN
  • $GOOGLE_ADS_DEVELOPER_TOKEN — 平台的开发者令牌（由服务端注入）→ 标头 developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN
  • login-customer-id — 仅用于管理器（MCC）范围的调用：请求所使用的管理器 ID，或已设置时的 $GOOGLE_ADS_LOGIN_CUSTOMER_ID（仅数字，不带连字符）。customers:listAccessibleCustomers 不需要此项。

API 版本：基础地址为 https://googleads.googleapis.com/<vNN>。Google 大约每 4 个月发布一个新的 vNN，并弃用旧版本，因此硬编码的版本最终会停止工作。示例使用 v25（截至 2026-07 受支持）。如果所有调用都返回 404，说明该版本不可用——可能已弃用，也可能尚未发布。探测 customers:listAccessibleCustomers：受支持的版本会返回 401/200，不可用的版本会返回 404。请从示例版本开始逐个降级，并在假定存在更新的 vNN 之前，先查看 Google 的受支持版本表。

如果 $GOOGLE_ADS_DEVELOPER_TOKEN 为空，说明连接器尚未完成配置——请说明这一点，不要调用 API（调用会返回 401/DEVELOPER_TOKEN_NOT_APPROVED）。

VER="v25"; BASE="https://googleads.googleapis.com/$VER"
AUTH="Authorization: Bearer $GOOGLE_ADS_TOKEN"; DEV="developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN"
# Customers the OAuth user can access (ids are returned as customers/<id>)
curl -sS -H "$AUTH" -H "$DEV" "$BASE/customers:listAccessibleCustomers" | jq '.resourceNames'

使用 GAQL（searchStream）生成报告

CID="1234567890"   # target customer id, digits only
# Manager (MCC) access → send login-customer-id; direct access → drop the header.
# Array, not a plain string: the header value contains a space and would split.
LOGIN=(); [ -n "$GOOGLE_ADS_LOGIN_CUSTOMER_ID" ] && LOGIN=(-H "login-customer-id: $GOOGLE_ADS_LOGIN_CUSTOMER_ID")
curl -sS -H "$AUTH" -H "$DEV" "${LOGIN[@]}" \
  -H "Content-Type: application/json" -d '{
  "query":"SELECT campaign.name, metrics.cost_micros, metrics.clicks, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"
}' "$BASE/customers/$CID/googleAds:searchStream" \
  | jq '.[].results[]? | {campaign: .campaign.name, cost_usd: (.metrics.costMicros|tonumber/1e6), clicks: .metrics.clicks, conv: .metrics.conversions}'

GAQL 资源：campaign、ad_group、ad_group_criterion（关键字）、 customer。费用字段为 metrics.cost_micros（除以 1,000,000 = 账户货币）。

注意事项

  • 每个端点都返回 404，说明问题在 VER，而不在凭据——版本已弃用或尚未发布。单个调用返回 404，则是该调用本身的问题：资源不存在（客户 ID 错误）或路径错误。在排查身份验证之前，请使用 customers:listAccessibleCustomers 检查版本。
  • 需要两个凭据和一个上下文标头。 每次调用都必须提供 developer-token；只有在管理器（MCC）账户下操作时，才需要 login-customer-id——customers:listAccessibleCustomers 无需此标头。在管理器范围的调用中省略该标头，是此处导致 401/403 的首要原因。
  • 客户 ID 在 URL/标头中只能包含数字（去掉 123-456-7890 中的连字符）。
  • searchStream 返回一个数组，其中每个分块都包含 .results[]——使用 .[].results[]? 展平。
  • 费用以账户货币的微单位表示；除以 1e6 即可。

评论

支持 Markdown