Skip to main content
skill CX Codex

google-ads · acedatacloud — Claude Code skill: what it does, how to install

Queries Google Ads campaigns, ad groups, keywords, and spend through the Google Ads API. Use it for campaign reports with clicks and conversions.

Apache-2.0 177 installs ★ 17 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add AceDataCloud/Skills --skill google-ads -a claude-code
Open on GitHub

What google-ads does

This skill calls the Google Ads API with curl and jq. It can list customers available to the OAuth user, then run GAQL queries through searchStream for campaigns, ad groups, keywords, and customer data. Campaign output can include cost, clicks, and conversions. Stream responses arrive in chunks, so the .results[] entries need to be flattened; metrics.cost_micros is converted to account currency by dividing by 1e6.

Set GOOGLE_ADS_TOKEN to the user's OAuth bearer and provide GOOGLE_ADS_DEVELOPER_TOKEN for the platform credential. Requests made under a manager account also use login-customer-id, while direct customer access does not. Customer IDs in URLs and headers contain digits only. Without GOOGLE_ADS_DEVELOPER_TOKEN, the connector should not call the API because authentication will fail.

What it helps with

  • list Google Ads customers the user can access
  • report campaign spend for a date range
  • compare clicks and conversions across campaigns
  • retrieve ad group and keyword performance
  • send requests under a manager account

Example prompts for the agent

  • List the Google Ads customers I can access and show their IDs.
  • Report campaign cost, clicks, and conversions for the last 30 days.
  • Query customer 1234567890 through the manager account and show campaign spend.

How to install google-ads

1Skills CLI (Vercel)

npx skills add AceDataCloud/Skills --skill google-ads -a claude-code

2Manually: put the files in place

~/.claude/skills/google-ads/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/google-ads/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about google-ads

How do I install google-ads in Claude Code?

Run npx skills add AceDataCloud/Skills --skill google-ads -a claude-code, then check ~/.claude/skills/google-ads/SKILL.md.

What does google-ads do?

It reads Google Ads through the API and GAQL searchStream, covering accessible customers, campaigns, ad groups, keywords, spend, clicks, and conversions.

Which credentials does google-ads need?

It needs the OAuth bearer in GOOGLE_ADS_TOKEN and the platform token in GOOGLE_ADS_DEVELOPER_TOKEN. Manager-account requests also need GOOGLE_ADS_LOGIN_CUSTOMER_ID, and customer IDs must use digits without dashes.

Source text

SKILL.md · Apache-2.0
---
name: google-ads
description: Query Google Ads campaigns, ad groups, keywords and spend via the Google Ads API (GAQL searchStream). Use when the user mentions Google Ads, ad campaigns, ad spend / cost, impressions / clicks / conversions on ads, or campaign performance.
when_to_use: |
  Trigger when the user wants Google Ads reporting — list accessible
  customers, campaign / ad-group / keyword performance, spend and
  conversions. Read via GAQL. Needs the OAuth token PLUS a platform
  developer token; if the developer token is absent the connector
  isn't fully provisioned yet — tell the user.
connections: [google/ads]
allowed_tools: [Bash]
license: Apache-2.0
metadata:
  author: acedatacloud
  version: "1.0"
---

Query the **Google Ads API** via `curl + jq`. Two credentials plus one context
header:

- `$GOOGLE_ADS_TOKEN` — the user's OAuth bearer (`adwords` scope) →
  `Authorization: Bearer $GOOGLE_ADS_TOKEN`
- `$GOOGLE_ADS_DEVELOPER_TOKEN` — the platform's developer token (injected
  server-side) → header `developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN`
- `login-customer-id` — **only for manager (MCC) scoped calls**: the manager id
  the request runs under, or `$GOOGLE_ADS_LOGIN_CUSTOMER_ID` if set (digits
  only, no dashes). Not needed by `customers:listAccessibleCustomers`.

> **API version:** the base is `https://googleads.googleapis.com/<vNN>`. Google
> ships a new `vNN` every ~4 months and retires old ones, so a hardcoded version
> eventually stops working. The example uses `v25` (supported as of 2026-07). If
> **every** call 404s, the version is unavailable — either retired or not yet
> released. Probe `customers:listAccessibleCustomers`: a supported version
> answers 401/200, an unavailable one 404. Step **down** one version at a time
> from the example, and check Google's supported-versions table before assuming
> a newer `vNN` exists.

If `$GOOGLE_ADS_DEVELOPER_TOKEN` is empty, the connector isn't fully provisioned —
say so rather than calling the API (it would 401/DEVELOPER_TOKEN_NOT_APPROVED).

```bash
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'
```

## Report with GAQL (searchStream)

```bash
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 resources: `campaign`, `ad_group`, `ad_group_criterion` (keywords),
`customer`. Cost is `metrics.cost_micros` (÷ 1,000,000 = account currency).

## Gotchas

- **A 404 on *every* endpoint points at `VER`, not at credentials** — the
  version is retired or unreleased. A 404 on a *single* call is about that call:
  a missing resource (bad customer id) or a wrong path. Sanity-check the version
  with `customers:listAccessibleCustomers` before debugging auth.
- **Two credentials plus a context header.** `developer-token` is required on
  every call; `login-customer-id` is only needed when acting under a manager
  (MCC) account — `customers:listAccessibleCustomers` works without it. Omitting
  it on a manager-scoped call is the #1 cause of 401/403 here.
- Customer ids are **digits only** in URLs/headers (strip the dashes from
  `123-456-7890`).
- `searchStream` returns an array of chunks each with `.results[]` — flatten with
  `.[].results[]?`.
- Cost is in **micros** of the account currency; divide by 1e6.

© acedatacloud · Apache-2.0 · AceDataCloud/Skills

Similar skills

All skills for Marketing and content →

google-ads by other authors comes first.

google-ads arnabbagxd Plans, structures, and optimizes Google Ads campaigns across Search, PMax, and YouTube. Useful when setting up ad tracking or building keyword sets. CX Codex +1 1,900installs google-ads kostja94 Guides Google Ads setup, keyword targeting, and campaign structure. It helps run ads to validate early product demand or scale acquisition. CX Codex +1 1,700installs google-ads OpenClaudia Build Google Ads campaign structures and draft copy for Search, Display, and Performance Max. Useful when planning a campaign or revising its ads. CX Codex +1 576installs google-ads membrane Manages Google Ads campaigns, budgets, and reporting directly from agent workflows using the Membrane CLI. CX Codex +1 214installs google-ads nowork-studio This Claude Code skill manages Google Ads campaigns, keywords, bids, and budgets. It activates for requests about CPA, ROAS, ad spend, or campaign settings. CX Codex +1 ★ 4,288repo stars Google Ads MCP scalably-io Read-only MCP server connecting Google Ads API to your assistant for GAQL reporting, keyword research, and change tracking. CX Codex +1 pp-google-ads mvanhorn pp-google-ads — a skill for Claude Code, Cursor and other AI editors that connects Google Ads API. Pulls reports via GAQL, manages campaigns, budgets, conversions and audiences. CX Codex +1 263installs ads-google AgriciDaniel ads-google — a skill for Claude Code, Codex, Cursor and other agents that audits Google Ads accounts: Search, Shopping, Performance Max, Demand Gen, bidding, budgets, negative keywords and conversion tracking. CX Codex +1 4,900installs google-ads-audit Cogny AI google-ads-audit audits Google Ads search queries and budget pacing via the Cogny MCP gateway. Helpful for catching wasted spend and missing negative keywords. CX Codex +1 ★ 116repo stars Google Ads get-mcp-ads Hooks a Google Ads account into your AI client: 35 read tools plus 13 write tools that stay off until you turn them on. CX Codex +1 ★ 1repo stars google-ads-manager claude-office-skills google-ads-manager helps plan Google Ads campaigns, group search keywords, write RSA ad copy, and prepare reporting. Useful when organizing paid search workflows. CX Codex +1 6,500installs

From the same set67

The whole set →

Project sponsors

Companies that keep this analytics open