<div align="right"> _{<strong>EN</strong> · <a href="README.es.md">Español</a>} </div> <p align="center"> <img src="assets/hero.png" alt="Claude Ads — tododeia editorial hero in black-and-white with rainbow accent. Giant 'claude-ads' wordmark with a red period-square, FREE-FIRST AUDIT · META · GOOGLE · TIKTOK eyebrow, meta blocks (PLATFORMS 3 · CHECKS 161 · COST $0), and two price cards (AUDIT PIPELINE $0 · /ads publish $0)." width="100%"> </p>

Claude Ads

A free Claude Code skill that turns Claude into your in-house paid-ads team — audits, plans, scores, reports.

---

What is this? (in plain English)

You know how you can ask Claude to review your code? Claude Ads is the same idea, but for paid advertising. Install it once, and Claude gets a brain transplant: it now knows Meta, Google, and TikTok Ads at a senior-strategist level — the 3 platforms where 95% of advertiser spend lives — with ~158 specific checks, 8 industry templates, and the ability to write you a real audit report at the end. Free-first: all 3 platforms have free community MCPs and free direct-API adapters.

You drop in your ad data (an export, a screenshot, or just paste your numbers), type a command like /ads audit, and Claude runs three deep-specialist analysts in parallel — one per platform. You get back a 0–100 health score, a prioritized punch list of what to fix, and (optionally) a polished PDF report you can hand a client.

It's not a magic button that runs your ads for you. It's a senior-level reviewer that lives inside your terminal, knows what's broken before you do, and never forgets to check the boring things (Consent Mode V2, CAPI, learning-phase rules, kill thresholds). And in v2.0+, it can update its own knowledge base monthly so it doesn't go stale.

New in v2.4.0 — /ads start walks first-time users from cold install to a working audit pipeline (context, OAuth, verification), and /ads next ranks Quick Wins after every audit so you always know exactly what to fix next.

---

Quick start (90 seconds)

Plugin install (recommended) — registers as a native Claude Code plugin with auto-updates:

/plugin marketplace add Hainrixz/claude-ads
/plugin install claude-ads@tododeia-claude-ads

Or one-liner install (Unix / macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/Hainrixz/claude-ads/main/install.sh | bash

Or one-liner install (Windows PowerShell):

irm https://raw.githubusercontent.com/Hainrixz/claude-ads/main/install.ps1 | iex

Then open Claude Code and run the first-time wizard:

claude
> /ads start

/ads start asks about your industry, monthly spend, and goals — then walks you through connecting Meta, Google, TikTok one at a time, step by step, with a live verification call after each. Optionally walks you through creating a Meta for Developers account and a Zernio account for /ads publish. Everything is saved to ~/.claude-ads/profile.json, so no future /ads command ever re-asks. When you're done it suggests your next command — usually /ads audit.

Already set up? You can also skip straight to:

> /ads audit       # full multi-platform audit
> /ads next        # top 3 fixes from your most recent audit

---

How it works

<p align="center"> <img src="assets/how-it-works.png" alt="How it works — three-stage flow in tododeia editorial style. Stage 01 INPUT: your ad data via MCP / scripts/api/ / manual exports. Stage 02 ORCHESTRATE: /ads orchestrator spawning audit-google (80 checks) · audit-meta (50 checks · MCP-wired) · audit-tiktok (28 checks). Stage 03 OUTPUT: Ads Health Score 78/100 with grade B." width="100%"> </p>

flowchart LR
  U([You]) -->|/ads audit| O[Orchestrator]
  O -.dispatches in parallel.-> G[audit-google · 80 checks]
  O -.-> M[audit-meta · 50 checks · MCP-wired]
  O -.-> T[audit-tiktok · 28 checks]
  G & M & T -->|MD + JSON findings| S[Scored report]
  S --> R([0–100 health score · prioritized fixes · optional PDF])

The orchestrator (/ads) doesn't try to do everything itself. It dispatches three deep-specialist agents in parallel — one per platform (audit-google, audit-meta, audit-tiktok), each with its own checklist (G* / M* / T* prefixed), its own reference data loaded on-demand (RAG style), and its own severity weights. Each agent emits both a human-readable Markdown report and a machine-readable JSON file validated against audit-output-schema.json. The orchestrator merges them into a single 0–100 Ads Health Score.

---

What you can run

| Group | Command | What it does | |---|---|---| | Onboard | /ads start | First-run wizard — context capture, per-platform OAuth/MCP walkthrough with live verification, optional Zernio + Meta Developers signup, profile persistence | | Coach | /ads next | Continuous coach — ranks top 3 next actions from your most recent audit + history, detects regressions, optionally walks you through fixing #1 | | Audit | /ads audit | Full multi-platform audit — 3 parallel agents (Meta, Google, TikTok), scored report | | Platform deep-dive | /ads google | Google Ads (Search, PMax, Demand Gen, CTV, includes YouTube video campaigns) — 80 checks | | | /ads meta | Meta Ads (FB / IG / Advantage+) — 50 checks · MCP-wired to claude.ai Facebook | | | /ads tiktok | TikTok Ads (Smart+, Shop, Symphony, GMV Max) — 28 checks | | Creative | /ads creative | Cross-platform creative quality + fatigue detection | | | /ads landing | Landing page conversion review | | Strategy | /ads plan <type> | Strategic plan from 8 industry templates | | | /ads budget | Budget allocation + bidding strategy review | | | /ads competitor | Competitor ad intelligence across all platforms | | Numbers | /ads math | PPC calculator: CPA, ROAS, break-even, LTV:CAC, MER | | | /ads test | A/B test design (hypothesis, sample size, duration) | | Output | /ads report | PDF audit report for client deliverables | | Maintenance | /ads update <platform\|all> | Refresh references with last-30-day platform changes (NEW in v2.0) |

---

Platforms covered

<p align="center"> <img src="assets/platforms.png" alt="Three platforms, free-first — tododeia editorial tile grid. META 50 checks (Pixel + CAPI · Andromeda · Advantage+) · GOOGLE 80 checks (Search · PMax · AI Max · Demand Gen incl YouTube) · TIKTOK 28 checks (Creative-first · Smart+ · GMV Max · Symphony) · CROSS-PLATFORM 3 checks (Privacy · Creative diversity · Refresh cadence)." width="100%"> </p>

| Platform | Checks | Focus areas | |---|---|---| | Google Ads | 80 | Search match types · PMax · AI Max · Demand Gen · CTV · YouTube video campaigns | | Meta Ads | 50 | Pixel + CAPI · Andromeda creative diversity · Advantage+ Shopping · audience structure | | TikTok Ads | 28 | Creative-first · Smart+ · GMV Max · Search Ads · Events API | | Cross-platform | 3 | Privacy infra · creative diversity · refresh cadence | | Total | ~158 platform + 3 cross-platform = 161 | weighted by severity into a 0–100 Ads Health Score |

Why these three? They cover ~95% of advertiser spend. Each has a free community MCP and a free direct-API adapter in this repo. Removed in v2.3.0: Apple Ads (no MCP exists), LinkedIn Ads (partner-program barrier + paid-only MCPs), Microsoft Ads (lower advertiser usage), YouTube Ads (lives inside Google Ads — covered via /ads google already).

---

Connect to your real ad accounts — three tiers, free-first

<p align="center"> <img src="assets/connect.png" alt="Connect your accounts — three-tier ladder in tododeia editorial style. 01 FREE ($0 forever): community MCPs + scripts/api/ direct adapters · 02 CONVENIENCE ($0 with claude.ai): claude.ai Facebook MCP one-click · 03 PAID SaaS opt-in ($0–$200/mo): Adspirer for Meta MCP commercial · Zernio for /ads publish (free for first 2 accounts)." width="100%"> </p>

Out of the box, Claude Ads runs in manual mode — paste exports / screenshots / numbers. That works on every plan, costs $0, requires zero setup. Everything else is opt-in. There are three tiers of integration:

Tier 1 — Free (recommended for individuals, solo agencies, indie shops) — $0

Two completely free ways to give claude-ads live data. Pick whichever has less friction for your platform:

1. Community MCP servers — open-source, run locally. Best when one exists for your platform:

   | Platform | MCP server | Cost | |---|---|---| | Meta | claude.ai Facebook MCP (connect in claude.ai's MCP catalog) ✓ already wired into audit-meta | $0 | | Meta | brijr/meta-mcp (self-hosted alt) | $0 | | Google | cohnen/mcp-google-ads | $0 | | TikTok | AdsMCP/tiktok-ads-mcp-server | $0 |

2. Direct API adapters — pure-stdlib scripts in scripts/api/ that fetch live data from each platform's official Marketing API. One-time OAuth setup per platform, then $0 forever. Run before invoking /ads <platform>:

   export META_ACCESS_TOKEN='...'
   python3 scripts/api/meta_fetch.py --account-id act_123 -o meta-data.json
   # Then in Claude Code: /ads meta — the agent reads meta-data.json automatically.
   

   Full setup per platform in scripts/api/README.md. Setup time: 5 min (Meta) to 1–3 business days (Google developer-token approval).

Tier 2 — Convenience — $0 with a claude.ai account

The official claude.ai Facebook MCP is technically Tier 1 (free), but it's the path of least resistance because you don't manage tokens at all — claude.ai handles OAuth on your behalf. Connect "Facebook" once in your claude.ai MCP catalog and the audit-meta agent finds it automatically.

Tier 3 — Paid SaaS (opt-in only)

Most users don't need this tier. Use only when:

• You want extra Meta features the official MCP doesn't expose → Adspirer (Meta MCP, commercial).
• You want to publish generated creatives to 14+ social networks (the /ads publish command) → Zernio is the only integration here. Zernio has nothing to do with the audit pipeline — it's strictly post-creative publishing. First 2 connected accounts are free forever (no credit card); agencies pay $1–$6/mo per additional account. So /ads publish is Tier 1 (free) for solo users / single brands and Tier 3 (paid) only once you're managing 3+ social accounts. See /ads publish below.

Heads up

Live mode means Claude can read — and with some MCP servers, write to — your real ad accounts. Start in read-only mode, point it at a sandbox or a low-spend account first, and only enable write access after a few clean runs. The full per-platform walkthrough is in ads/references/mcp-integration.md and scripts/api/README.md.

---

Industry templates

/ads plan <type> builds a full strategic ad plan from a template tuned to your business model — platform mix, campaign architecture, creative angles, targeting, budget split, and KPI targets included. Twelve are bundled:

| Template | Use it for | |---|---| | ecommerce | DTC + eco