Menu
AI-powered Google Ads campaign management — create, optimize, audit, and report on PPC campaigns
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Manage projects on Nulab Backlog — issues, wikis, milestones, Git, sprints for Japan's top PM tool
Automate Japan's
Unified Gmail, Calendar, Drive, Sheets, and Docs management from Claude Code
Task and project management on Jooto — create tasks, manage boards, automate workflows via PR TIMES' tool
Attendance and time tracking automation — daily/monthly data, payroll sync via Japan's leading attendance system
Build, query, and automate Cybozu kintone apps — Japan's leading no-code business platform
| name | google-ads-agent |
| description | AI-powered Google Ads campaign management — create, optimize, audit, and report on PPC campaigns |
| author | hanabi-jpn |
| version | 1.0.0 |
| tags | ["google-ads","ppc","advertising","campaign-management","bid-optimization","keyword-research","marketing"] |
╔═══════════════════════════════════════════════╗
║ ┌─────────────────────────────────────────┐ ║
║ │ G O O G L E A D S A G E N T │ ║
║ │ ━━━━━━━━━━━━━━━━━━━━ │ ║
║ │ 📊 Campaign → Keywords → Optimize │ ║
║ │ AI-Powered Ad Management │ ║
║ └─────────────────────────────────────────┘ ║
╚═══════════════════════════════════════════════╝
google-ads ppc-automation bid-optimizer quality-score campaign-manager
Turn Google Ads complexity into conversational simplicity -- manage million-dollar ad budgets with natural language commands.
Google Ads Agent transforms Claude Code into a full-featured PPC campaign management console. Instead of navigating the labyrinthine Google Ads UI or writing raw API calls against the Google Ads API, you issue plain-English commands and receive structured, actionable results. The agent handles everything from initial campaign creation to ongoing bid optimization, keyword expansion, quality score remediation, and executive-ready reporting.
Under the hood, the agent authenticates via OAuth 2.0, constructs Google Ads Query Language (GAQL) queries, and translates API responses into human-readable output with inline recommendations. It maintains session context so you can drill down from account-level metrics to individual ad group performance without re-specifying parameters. The architecture supports multi-account (MCC) setups, enabling agency workflows where a single operator manages dozens of client accounts from one terminal session.
Architecture:
+------------------+ +---------------------+ +--------------------+
| Claude Code | ----> | Google Ads Agent | ----> | Google Ads API |
| (User CLI) | | (SKILL Engine) | | (v17 REST/gRPC) |
+------------------+ +---------------------+ +--------------------+
| | |
| Natural Language | GAQL Query Builder | Campaign Data
| Commands | OAuth2 Token Mgmt | Keyword Planner
| | Response Formatter | Bid Simulator
v v v
+------------------+ +---------------------+ +--------------------+
| Terminal Output | | Local Cache Layer | | Google Keyword |
| Tables / Charts | | ~/.ads-agent/ | | Planner API |
+------------------+ +---------------------+ +--------------------+
You are Google Ads Agent, an expert PPC campaign management assistant operating within Claude Code. Follow these rules precisely:
~/.ads-agent/ to reduce API calls. Invalidate cache after 1 hour or on explicit refresh.| Variable | Required | Default | Description |
|---|---|---|---|
GOOGLE_ADS_DEVELOPER_TOKEN | Yes | -- | Developer token from Google Ads API Center |
GOOGLE_ADS_CLIENT_ID | Yes | -- | OAuth 2.0 client ID |
GOOGLE_ADS_CLIENT_SECRET | Yes | -- | OAuth 2.0 client secret |
GOOGLE_ADS_REFRESH_TOKEN | Yes | -- | OAuth 2.0 refresh token for offline access |
GOOGLE_ADS_CUSTOMER_ID | Yes | -- | Target account customer ID (without dashes) |
GOOGLE_ADS_LOGIN_CUSTOMER_ID | No | Same as CUSTOMER_ID | MCC manager account ID for multi-account access |
ADS_AGENT_CACHE_DIR | No | ~/.ads-agent/ | Local cache directory for account structure |
ADS_AGENT_DEFAULT_DATE_RANGE | No | LAST_30_DAYS | Default reporting date range |
ads campaignsList all campaigns with key performance metrics.
$ ads campaigns
Google Ads Agent v1.0.0 — Account: 123-456-7890 (Acme Corp)
Date Range: 2026-02-01 to 2026-02-28
┌─────────────────────────────┬──────────┬───────────┬────────────┬────────┬───────┬────────┬───────────┬──────┐
│ Campaign │ Status │ Budget/d │ Impress. │ Clicks │ CTR │ Avg CPC│ Conversns │ Cost │
├─────────────────────────────┼──────────┼───────────┼────────────┼────────┼───────┼────────┼───────────┼──────┤
│ Brand - Exact Match │ ENABLED │ $150.00 │ 42,318 │ 8,912 │ 21.1% │ $0.42 │ 1,247 │ $3,743│
│ Non-Brand - General │ ENABLED │ $500.00 │ 318,204 │ 6,441 │ 2.0% │ $2.14 │ 389 │ $13,784│
│ Shopping - All Products │ ENABLED │ $300.00 │ 156,890 │ 4,210 │ 2.7% │ $1.08 │ 612 │ $4,547│
│ Display - Remarketing │ PAUSED │ $100.00 │ 0 │ 0 │ 0.0% │ $0.00 │ 0 │ $0 │
│ Performance Max - Lead Gen │ ENABLED │ $250.00 │ 89,512 │ 2,108 │ 2.4% │ $2.87 │ 278 │ $6,050│
└─────────────────────────────┴──────────┴───────────┴────────────┴────────┴───────┴────────┴───────────┴──────┘
Total Spend: $28,124.00 | Total Conversions: 2,526 | Avg CPA: $11.13
Recommendations:
1. "Display - Remarketing" is paused — consider reactivating to capture warm audiences
2. "Non-Brand - General" CPA ($35.43) is 3.2x account average — review keyword list
3. "Brand - Exact Match" has headroom — budget utilization at 89%, consider +15%
ads createCreate a new campaign with guided configuration.
$ ads create --type search --name "Spring Sale 2026" --budget 200 --target-cpa 15
Creating Search Campaign...
Campaign: Spring Sale 2026
├── Type: Search
├── Budget: $200.00/day
├── Bidding: Target CPA ($15.00)
├── Networks: Google Search + Search Partners
├── Locations: United States (inherited from account)
├── Languages: English
└── Start Date: 2026-03-01 (today)
Default Ad Group Created: "Spring Sale - General"
└── Status: PAUSED (add keywords and ads to activate)
Next steps:
1. Run `ads keywords add "Spring Sale 2026"` to add keywords
2. Create responsive search ads with `ads create-ad "Spring Sale - General"`
3. Enable campaign with `ads enable "Spring Sale 2026"`
Campaign ID: 20461893027 — Created successfully.
ads keywordsResearch and manage keywords for a campaign.
$ ads keywords research "ergonomic office chair" --limit 10
Keyword Research — Seed: "ergonomic office chair"
┌──────────────────────────────────┬──────────────┬─────────────┬───────────┬──────────────┐
│ Keyword │ Avg Monthly │ Competition │ Low Bid │ High Bid │
├──────────────────────────────────┼──────────────┼─────────────┼───────────┼──────────────┤
│ ergonomic office chair │ 201,000 │ HIGH │ $1.22 │ $4.87 │
│ best ergonomic chair │ 110,000 │ HIGH │ $0.98 │ $3.91 │
│ ergonomic desk chair │ 74,000 │ HIGH │ $1.05 │ $4.12 │
│ office chair lumbar support │ 49,500 │ MEDIUM │ $0.87 │ $3.24 │
│ ergonomic chair for back pain │ 33,100 │ MEDIUM │ $0.92 │ $3.56 │
│ adjustable office chair │ 27,100 │ MEDIUM │ $0.74 │ $2.98 │
│ ergonomic task chair │ 18,100 │ LOW │ $0.68 │ $2.41 │
│ mesh ergonomic office chair │ 14,800 │ MEDIUM │ $0.91 │ $3.77 │
│ ergonomic chair under 300 │ 12,100 │ MEDIUM │ $0.82 │ $3.15 │
│ standing desk chair ergonomic │ 8,100 │ LOW │ $0.71 │ $2.89 │
└──────────────────────────────────┴──────────────┴─────────────┴───────────┴──────────────┘
Estimated monthly traffic at $3.00 max CPC: 4,200-6,800 clicks
Suggested negative keywords: "used", "repair", "diy", "reddit"
ads optimizeRun bid optimization with projected impact analysis.
$ ads optimize "Non-Brand - General" --target-cpa 20
Bid Optimization Analysis — "Non-Brand - General"
Current Target CPA: $35.43 | Proposed: $20.00
Projected Impact (next 30 days):
┌────────────────────┬──────────────┬──────────────┬─────────────┐
│ Metric │ Current │ Projected │ Change │
├────────────────────┼──────────────┼──────────────┼─────────────┤
│ Daily Budget │ $500.00 │ $500.00 │ -- │
│ Impressions │ 318,204 │ 245,100 │ -23.0% │
│ Clicks │ 6,441 │ 5,820 │ -9.6% │
│ Conversions │ 389 │ 485 │ +24.7% │
│ CPA │ $35.43 │ $20.62 │ -41.8% │
│ ROAS │ 2.8x │ 4.1x │ +46.4% │
└────────────────────┴──────────────┴──────────────┴─────────────┘
Low-performing keywords to reduce/pause (5):
- "office supplies general" CPA: $89.12 → Recommend: PAUSE
- "cheap furniture online" CPA: $67.40 → Recommend: PAUSE
- "workspace setup ideas" CPA: $52.18 → Recommend: Reduce bid 40%
- "home office decor" CPA: $48.90 → Recommend: Reduce bid 35%
- "desk accessories bulk" CPA: $41.22 → Recommend: Reduce bid 20%
Apply these changes? (y/n):
ads budgetAnalyze and adjust campaign budgets.
$ ads budget summary
Budget Summary — Account: 123-456-7890
Billing Period: 2026-03-01 to 2026-03-31 (31 days remaining)
┌─────────────────────────────┬───────────┬───────────┬───────────┬──────────┐
│ Campaign │ Daily Cap │ MTD Spend │ Projected │ Utiliz. │
├─────────────────────────────┼───────────┼───────────┼───────────┼──────────┤
│ Brand - Exact Match │ $150.00 │ $0.00 │ $4,185 │ 89% │
│ Non-Brand - General │ $500.00 │ $0.00 │ $14,920 │ 96% │
│ Shopping - All Products │ $300.00 │ $0.00 │ $8,742 │ 94% │
│ Performance Max - Lead Gen │ $250.00 │ $0.00 │ $7,440 │ 96% │
├─────────────────────────────┼───────────┼───────────┼───────────┼──────────┤
│ TOTAL │ $1,200/d │ $0.00 │ $35,287 │ 95% │
└─────────────────────────────┴───────────┴───────────┴───────────┴──────────┘
Budget is on track. No overspend risk detected.
ads quality-scoreDiagnose quality score issues at the keyword level.
$ ads quality-score "Brand - Exact Match" --below 7
Quality Score Analysis — "Brand - Exact Match"
Showing keywords with QS < 7
┌────────────────────────┬────┬──────────────┬──────────────┬────────────────┐
│ Keyword │ QS │ Expected CTR │ Ad Relevance │ Landing Page │
├────────────────────────┼────┼──────────────┼──────────────┼────────────────┤
│ acme corporation │ 6 │ Average │ Above Avg │ Below Average │
│ acme corp products │ 5 │ Below Avg │ Average │ Below Average │
│ acme online store │ 4 │ Below Avg │ Below Avg │ Below Average │
└────────────────────────┴────┴──────────────┴──────────────┴────────────────┘
Remediation Plan:
1. Landing Page (3 keywords affected):
- Page load time is 4.2s (target: <2.5s) — optimize images and defer JS
- Mobile usability score: 62/100 — fix viewport and tap targets
2. Expected CTR (2 keywords affected):
- Add keyword insertion {KeyWord:Acme} to headline 1
- Test countdown customizers for urgency
3. Ad Relevance (1 keyword affected):
- "acme online store" not present in any ad copy — create dedicated ad
ads reportGenerate formatted performance reports.
$ ads report --period "last 7 days" --format summary
Performance Report — 2026-02-22 to 2026-02-28
Account: 123-456-7890 (Acme Corp)
Account Highlights:
Spend: $6,842.18
Impressions: 148,291
Clicks: 5,417
CTR: 3.65%
Conversions: 632
CPA: $10.83
ROAS: 5.2x
Week-over-Week Trends:
Spend ████████████████░░░░ +8.2%
Clicks ███████████████░░░░░ +5.1%
Conversions ██████████████████░░ +12.4%
CPA ██████░░░░░░░░░░░░░░ -3.7% (improving)
Top Performing Campaign: "Brand - Exact Match" (ROAS: 12.4x)
Needs Attention: "Non-Brand - General" (CPA up 18% WoW)
ads ab-testCreate and analyze A/B tests for ad variants.
$ ads ab-test analyze "Spring Sale - General"
A/B Test Results — Ad Group: "Spring Sale - General"
Test Duration: 14 days | Status: SIGNIFICANT
┌──────────────────┬──────────────┬──────────────┬─────────────┐
│ Metric │ Variant A │ Variant B │ Winner │
├──────────────────┼──────────────┼──────────────┼─────────────┤
│ Impressions │ 12,418 │ 12,205 │ -- │
│ Clicks │ 496 │ 612 │ B (+23.4%) │
│ CTR │ 4.00% │ 5.01% │ B │
│ Conversions │ 41 │ 58 │ B (+41.5%) │
│ Conv. Rate │ 8.27% │ 9.48% │ B │
│ CPA │ $14.22 │ $10.18 │ B (-28.4%) │
└──────────────────┴──────────────┴──────────────┴─────────────┘
Statistical Confidence: 94.7% (threshold: 90%)
Recommendation: Pause Variant A, allocate full budget to Variant B.
Variant B headline: "Ergonomic Chairs — 40% Off Spring Sale"
ads auditRun a comprehensive account health audit.
$ ads audit
Account Audit — 123-456-7890 (Acme Corp)
Score: 74/100 (Good)
[PASS] Conversion tracking is active (Google Tag + Enhanced Conversions)
[PASS] Brand/Non-Brand campaigns are properly segmented
[PASS] Negative keyword lists are shared across campaigns (3 lists)
[WARN] 12 ad groups have only 1 ad variant — add at least 2 for testing
[WARN] 47 keywords have QS below 5 — review landing pages
[FAIL] No audience lists applied to Search campaigns for observation
[FAIL] Display - Remarketing has been paused for 45+ days — remove or reactivate
[WARN] 5 campaigns missing sitelink extensions — expected coverage: 100%
Priority Actions:
1. Add audience observation to all Search campaigns Impact: HIGH
2. Fix quality scores on 47 keywords Impact: HIGH
3. Add second ad variant to 12 ad groups Impact: MEDIUM
4. Resolve paused Display campaign Impact: LOW
5. Add sitelinks to 5 campaigns Impact: MEDIUM
ads pausePause campaigns, ad groups, or keywords with confirmation.
$ ads pause keyword "cheap furniture online" --campaign "Non-Brand - General"
Pause Confirmation:
Target: Keyword "cheap furniture online" [BROAD]
Campaign: Non-Brand - General
Ad Group: Furniture - General
Last 30d: 142 clicks | 0 conversions | $304.12 spend
This keyword has spent $304.12 with zero conversions. Pausing is recommended.
Proceed? (y/n): y
Keyword paused successfully.
Estimated monthly savings: $304.12
Remaining keywords in ad group: 23 (18 active)
ads create
|
v
┌─────────────┐ ┌─────────────────────┐ ┌──────────────────┐
│ Keyword │────>│ Campaign Setup │────>│ Launch │
│ Research │ │ Budget / Bids / Geo │ │ Monitor │
└─────────────┘ └─────────────────────┘ └──────────────────┘
|
┌────────────────────────────────────────┘
v
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Performance │────>│ Optimize │────>│ A/B Test │
│ Monitoring │ │ Bids / Keywords │ │ Ad Variants │
└──────────────────┘ └──────────────────┘ └──────────────────┘
|
┌────────────────────────────────────────┘
v
┌──────────────────┐ ┌──────────────────┐
│ Quality Score │────>│ Reporting & │
│ Remediation │ │ Audit │
└──────────────────┘ └──────────────────┘
| Error | Cause | Solution |
|---|---|---|
AUTH_ERROR: Invalid refresh token | Refresh token expired or revoked | Re-generate refresh token via ads auth refresh. Tokens expire if unused for 6 months. |
QUOTA_EXCEEDED: Daily operation limit reached | Exceeded 15,000 daily API operations | Wait until midnight PT for quota reset. Use --dry-run for testing queries without consuming quota. |
CUSTOMER_NOT_FOUND: Invalid customer ID | Wrong customer ID or missing MCC access | Verify GOOGLE_ADS_CUSTOMER_ID format (no dashes). For MCC, set GOOGLE_ADS_LOGIN_CUSTOMER_ID. |
MUTATE_ERROR: Campaign budget below minimum | Budget set below Google's $1.00/day minimum | Set daily budget to at least $1.00. Google requires a minimum for all campaign types. |
KEYWORD_ERROR: Duplicate keyword in ad group | Attempting to add a keyword that already exists with the same match type | Use ads keywords list to check existing keywords. Change match type or target a different ad group. |
RESOURCE_NOT_FOUND: Campaign ID does not exist | Referencing a deleted or non-existent campaign | Run ads campaigns --include-removed to check. Campaign may have been removed from another interface. |
RATE_LIMIT: Too many requests | Burst of API calls exceeded per-second limit | Agent automatically retries with exponential backoff. If persistent, reduce concurrent operations. |
All local data is stored in ~/.ads-agent/:
~/.ads-agent/
├── config.json # Account configuration and preferences
├── cache/
│ ├── account_tree.json # Campaign/ad group structure (1hr TTL)
│ ├── keyword_cache.json # Recent keyword research results
│ └── quality_scores.json # Latest QS snapshot
├── history/
│ ├── mutations.log # All write operations with timestamps
│ └── undo_stack.json # Last 10 reversible operations
└── reports/
└── YYYY-MM-DD_report.json # Exported report data
Data is stored locally only. No telemetry or external data transmission occurs beyond Google Ads API calls. The cache can be cleared with ads cache clear.
| Feature | Google Ads Agent | Google Ads UI | Google Ads Editor | Optmyzr |
|---|---|---|---|---|
| Natural language queries | Yes | No | No | Limited |
| CLI-based workflow | Yes | No | No | No |
| Bulk operations | Yes | Limited | Yes | Yes |
| AI-powered recommendations | Yes (inline) | Basic | No | Yes |
| A/B test analysis | Automated | Manual | No | Semi-auto |
| Quality score diagnostics | Detailed breakdown | Basic view | Basic view | Yes |
| Multi-account (MCC) | Yes | Yes | Yes | Yes |
| Custom reporting | Yes (terminal) | Yes (web) | Export only | Yes |
| Offline editing | Cache-based | No | Yes | No |
| Cost | Free (open source) | Free | Free | $208+/mo |
| Integration with dev tools | Native (Claude Code) | None | None | API only |
1. How do I get a Google Ads Developer Token? Apply through your Google Ads Manager account under Tools > API Center. Basic access is granted for test accounts; standard access requires a review application describing your use case. The process typically takes 3-5 business days.
2. Can I manage multiple Google Ads accounts?
Yes. Set GOOGLE_ADS_LOGIN_CUSTOMER_ID to your MCC manager account ID, then switch between child accounts using ads account switch <customer-id>. All commands will target the selected account.
3. Will the agent make changes without my approval?
Never. All write operations (create, update, pause, delete) require explicit confirmation. Use --dry-run on any command to preview changes without applying them.
4. How does bid optimization work? The agent queries Google's Bid Simulator API to project performance at different bid levels, then recommends adjustments based on your target CPA or ROAS. It respects maximum bid caps and shows the projected impact before applying changes.
5. Is there a risk of overspending my budget? The agent checks remaining billing period days before any budget change and warns if projected spend would exceed your monthly target. It never increases budgets without confirmation.
6. Can I export reports to CSV or PDF?
Yes. Append --export csv or --export pdf to any report command. Files are saved to ~/.ads-agent/reports/.
7. How fresh is the data? Campaign metrics are queried in real-time from the Google Ads API. Some metrics (like conversions) have a 24-72 hour attribution delay inherent to Google Ads, not the agent.
8. Does it support Performance Max campaigns?
Yes. Performance Max campaigns are fully supported for monitoring, budget management, and reporting. Asset group management is available via ads pmax-assets.
9. What happens if my API quota runs out?
The agent displays a clear error message with the reset time (midnight Pacific). It also shows remaining quota at the end of every session. Use ads quota to check anytime.
10. Can I undo a change?
Yes. The last 10 write operations are stored in the undo stack. Run ads undo to reverse the most recent change. Multi-step undos are available with ads undo --steps 3.
11. How do I handle seasonal campaigns?
Use ads create --start-date 2026-12-01 --end-date 2026-12-31 to set campaign flight dates. The agent will automatically factor in the limited date range when projecting performance and budgets.
12. Can I schedule commands to run automatically?
The agent itself does not include a scheduler, but you can combine it with cron jobs or CI/CD pipelines. Example: 0 8 * * 1 ads report --period "last 7 days" --export csv sends a weekly report every Monday at 8 AM.