Skip to content

Hainrixz/claude-ads / ads

Free-first paid advertising audit and optimization skill, focused on the 3 platforms where 95% of advertiser spend lives: Meta, Google, TikTok. Guided onboarding (/ads start) saves context once and step-by-step OAuth walkthroughs; continuous coach (/ads next) ranks Quick Wins after each audit. ~158 weighted checks with scoring, parallel agents, industry templates, and AI creative generation.

FileKindSize
SKILL.mdskill md18.6 KB
references/additional-platforms.mdmarkdown3.6 KB
references/audit-history-schema.jsonconfig2.5 KB
references/audit-methodology.mdmarkdown4.3 KB
references/audit-output-schema.jsonconfig4.9 KB
references/benchmarks-cross.mdmarkdown1003 B
references/benchmarks-google.mdmarkdown1.6 KB
references/benchmarks-social.mdmarkdown2.6 KB
references/benchmarks.mdmarkdown929 B
references/bidding-google.mdmarkdown5.2 KB
references/bidding-meta.mdmarkdown1.8 KB
references/bidding-strategies.mdmarkdown989 B
references/bidding-tiktok.mdmarkdown2.0 KB
references/brand-dna-template.mdmarkdown6.9 KB
references/budget-allocation.mdmarkdown5.8 KB
references/compliance-changes-2025-2026.mdmarkdown2.5 KB
references/compliance-platforms.mdmarkdown3.6 KB
references/compliance-privacy.mdmarkdown3.1 KB
references/compliance.mdmarkdown1.6 KB
references/conciencia-schema.jsonconfig5.3 KB
references/conciencia.mdmarkdown5.2 KB
references/conversion-tracking.mdmarkdown1.2 KB
references/copy-frameworks.mdmarkdown8.9 KB
references/gaql-notes.mdmarkdown2.8 KB
references/google-audit-notes.mdmarkdown3.9 KB
references/google-audit.mdmarkdown12.5 KB
references/google-changelog-30d.mdmarkdown3.6 KB
references/google-creative-specs.mdmarkdown3.7 KB
references/image-providers.mdmarkdown4.9 KB
references/mcp-integration.mdmarkdown5.7 KB
references/mcp-meta-integration.mdmarkdown5.8 KB
references/meta-audit.mdmarkdown12.4 KB
references/meta-changelog-30d.mdmarkdown4.0 KB
references/meta-creative-specs.mdmarkdown4.5 KB
references/platform-specs-cross.mdmarkdown1.3 KB
references/platform-specs.mdmarkdown799 B
references/profile-schema.jsonconfig4.5 KB
references/scoring-system.mdmarkdown6.1 KB
references/setup-google.mdmarkdown7.1 KB
references/setup-meta-developers.mdmarkdown4.7 KB
references/setup-meta.mdmarkdown7.0 KB
references/setup-tiktok.mdmarkdown5.2 KB
references/setup-zernio.mdmarkdown4.5 KB
references/tiktok-audit.mdmarkdown10.1 KB
references/tiktok-changelog-30d.mdmarkdown3.5 KB
references/tiktok-creative-specs.mdmarkdown4.8 KB
references/tracking-cross.mdmarkdown1.5 KB
references/tracking-google.mdmarkdown2.8 KB
references/tracking-meta.mdmarkdown2.4 KB
references/tracking-tiktok.mdmarkdown1.5 KB
references/update-cost-warning.mdmarkdown2.0 KB
references/voice-to-style.mdmarkdown3.9 KB
research-sources/README.mdmarkdown883 B
research-sources/claude-research.mdmarkdown3.9 KB
research-sources/gemini-research.mdmarkdown10.2 KB
research-sources/google-audit-checklists.mdmarkdown25.9 KB
research-sources/google-optimization-logic.mdmarkdown11.9 KB
research-sources/google-platform-specs.mdmarkdown16.6 KB

references/setup-google.md

View on GitHub
# Setup: Google Ads (Search, PMax, YouTube)

Loaded by `/ads start` Phase C when the user picks Google. Three sections —
**A** for the MCP path, **B** for Direct API, **C** for Manual exports.
Section B has a 1–3 business-day waiting period for developer-token approval;
warn the user upfront so they can pick A or C first if they need same-day.

---

## Section A — cohnen/mcp-google-ads (Capa 1)

Effort: ~10 min for first-time install (still needs OAuth client + refresh
token; same env vars as Capa 2). Worth it because the MCP exposes natural-
language GAQL.

### STEP A1 — Confirm Python + pip available
- **Goal**: prerequisite check.
- **Do this**: `python3 --version` (need 3.10+) and `pip3 --version`.
- **Expect to see**: Python ≥3.10.
- **On error**: install Python via `brew install python` (mac) or the
  python.org installer.

### STEP A2 — Install the MCP server
- **Goal**: have the server binary on disk.
- **Do this**:
  ```bash
  pip3 install mcp-google-ads
  ```
- **Expect to see**: `Successfully installed mcp-google-ads-...`.
- **On error**: permission denied → `pip3 install --user mcp-google-ads`.

### STEP A3 — Reuse Direct API credentials
- **Goal**: the MCP needs the same env vars as Section B. Either set them now
  or come back after Section B.
- **Do this**: ensure these are exported:
  `GOOGLE_ADS_DEVELOPER_TOKEN`, `GOOGLE_ADS_CLIENT_ID`,
  `GOOGLE_ADS_CLIENT_SECRET`, `GOOGLE_ADS_REFRESH_TOKEN`,
  (optional) `GOOGLE_ADS_LOGIN_CUSTOMER_ID`.
- **Expect to see**: `echo $GOOGLE_ADS_DEVELOPER_TOKEN` prints non-empty.
- **On error**: missing → go run Section B steps B1–B5 first, then return.

### STEP A4 — Wire to Claude Code MCP config
- **Goal**: tell Claude Code to launch the server.
- **Do this**: edit `~/.claude/mcp_servers.json` (or your team's MCP config)
  to add:
  ```json
  { "google-ads": { "command": "python3", "args": ["-m", "mcp_google_ads"] } }
  ```
  Restart Claude Code.
- **Expect to see**: in this chat, `/mcp` lists `mcp__google_ads__*` tools.
- **On error**: tools missing → check `~/.claude/logs/mcp-*.log` for the
  server's stderr. Most often: refresh-token expired (redo Step B4).

### STEP A5 — Verify
- **Goal**: live call returns customer list.
- **Do this**: agent calls `mcp__google_ads__list_customers` (or similar
  per the server's tool catalog).
- **Expect to see**: array with ≥1 customer ID.
- **On error**: empty → user's OAuth grant didn't include the right
  customer; redo refresh-token generation with the correct Google account.

Save: `tier = mcp_cohnen`, `ad_account_id = <customer_id>`,
`connected_at`, `last_verified_at`.

---

## Section B — Direct API (Capa 2)

Effort: 1–3 business days for dev-token approval, then ~10 min OAuth.

### STEP B1 — Apply for developer-token
- **Goal**: get an API key that can talk to Google Ads.
- **Do this**: sign in to your MCC (manager) account → top-right tools icon
  → **API Center** → fill the application. Start at **Test access level**
  (instant; only works against test accounts). Apply for **Basic** for real
  data. URL: https://ads.google.com/aw/apicenter
- **Expect to see**: developer token displayed (string like `aBcD-1234...`).
- **On error**: "You must be on an MCC" → create an MCC at
  https://ads.google.com/home/tools/manager-accounts/ and link the operating
  account to it.

### STEP B2 — Create OAuth 2.0 client
- **Goal**: a client_id + client_secret to exchange for tokens.
- **Do this**: https://console.cloud.google.com → **APIs & Services** →
  **Credentials** → Create Credentials → OAuth client ID → application type
  **Desktop app** → name "claude-ads" → Create.
- **Expect to see**: a dialog with `client_id` and `client_secret`. Save
  both. Also click **Download JSON** if you prefer file-based config.
- **On error**: "Configure OAuth consent screen first" → do that (External,
  test users = your own Google account).

### STEP B3 — Enable the Google Ads API
- **Goal**: turn the API on in the GCP project.
- **Do this**: APIs & Services → **Enabled APIs & Services** → + ENABLE APIS
  → search "Google Ads API" → Enable.
- **Expect to see**: status "Enabled".

### STEP B4 — Generate a refresh token
- **Goal**: long-lived token that the script can refresh automatically.
- **Do this**: easiest path is the [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/):
  gear icon → tick **Use your own OAuth credentials** → paste client_id/
  secret → scope `https://www.googleapis.com/auth/adwords` → Authorize APIs
  → Sign in → **Exchange authorization code for tokens** → copy
  `refresh_token`.
- **Expect to see**: a string starting with `1//...`.
- **On error**: `redirect_uri_mismatch` → in GCP Credentials, add
  `https://developers.google.com/oauthplayground` as an authorized redirect
  URI.

### STEP B5 — Find customer_id + login_customer_id
- **Goal**: pick which account to query.
- **Do this**: in Google Ads UI, the 10-digit ID is top-right next to the
  account name (format `123-456-7890` — strip dashes for env vars).
  `login_customer_id` is the MCC ID if the operating account sits under one.
- **Expect to see**: a 10-digit number.

### STEP B6 — Export env vars + verify
- **Goal**: prove `google_fetch.py` works.
- **Do this**:
  ```bash
  export GOOGLE_ADS_DEVELOPER_TOKEN='...'
  export GOOGLE_ADS_CLIENT_ID='....apps.googleusercontent.com'
  export GOOGLE_ADS_CLIENT_SECRET='GOCSPX-...'
  export GOOGLE_ADS_REFRESH_TOKEN='1//...'
  export GOOGLE_ADS_LOGIN_CUSTOMER_ID='1234567890'   # MCC, if applicable
  python3 scripts/api/google_fetch.py --account-id 1234567890 --what account
  ```
- **Expect to see**: JSON with `platform: "google"`, `errors: []`.
- **On error**: `DEVELOPER_TOKEN_NOT_APPROVED` → still on Test level; either
  use a test account or wait for Basic approval. `USER_PERMISSION_DENIED` →
  the Google account that authorized OAuth doesn't have access to the
  customer.

Save: `tier = direct_api`, `ad_account_id = <customer_id>`,
`connected_at`, `last_verified_at`.

---

## Section C — Manual exports (Capa 3)

### STEP C1 — Export Search Terms Report
- **Do this**: Reports → Predefined reports → **Search terms** → date range
  last 28 days → Download CSV.

### STEP C2 — Export Campaigns report
- **Do this**: Campaigns tab → Download → CSV. Columns: Campaign, Status,
  Bid strategy, Budget, Cost, Impressions, Clicks, Conversions, Conv. value.

### STEP C3 — Capture Change History
- **Do this**: Tools → **Change History** → last 30 days → screenshot or CSV.

Save: `tier = manual`, `ad_account_id = <customer_id>` (10-digit, no dashes),
`connected_at`. Leave `last_verified_at = null`.

---

## Troubleshooting summary

| Symptom | Cause | Fix |
|---------|-------|-----|
| `DEVELOPER_TOKEN_NOT_APPROVED` | Test-level token vs production account | Wait for Basic, or use a test account |
| `redirect_uri_mismatch` | Playground URL not in GCP credentials | Add it in Step B2 |
| `USER_PERMISSION_DENIED` | OAuth'd Google user can't see customer | Re-auth with the right Google account |
| MCC errors | Operating account not under MCC | Add `GOOGLE_ADS_LOGIN_CUSTOMER_ID` |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall