Google Ads Agent — Gemini CLI Extension

A Gemini CLI extension that gives you live Google Ads API access from your terminal. Ask questions about your campaigns, find wasted spend, audit accounts, get optimization recommendations — all through natural conversation.

Built from production learnings running an AI Google Ads agent at googleadsagent.ai — 28 custom API actions, 6 sub-agents, managing real Google Ads accounts via the Google Ads API v22.

Quick Start (5 minutes)

Step 1: Install Node.js (if you don't have it)

# Check if you already have it
node --version

# If not, install via Homebrew (macOS)
brew install node

# Or download from https://nodejs.org (Windows/Linux/macOS)

Step 2: Install Gemini CLI

npm install -g @google/gemini-cli

Step 3: Get a Gemini API key (free)

1. Go to aistudio.google.com/apikey
2. Click Create API Key
3. Copy it, then save it:

mkdir -p ~/.gemini
echo 'GEMINI_API_KEY=your-key-here' > ~/.gemini/.env

The free tier gives you 60 requests/minute and 1,000/day — more than enough.

Step 4: Install this extension

gemini extensions install https://github.com/itallstartedwithaidea/google-ads-gemini-extension

You'll be prompted to confirm the install and enter your Google Ads credentials (see Getting Credentials below). Sensitive values are stored in your system keychain.

Step 5: Start using it

gemini

That's it. The extension auto-loads every time. Just start asking questions:

> Show me my Google Ads accounts
> How are my campaigns performing this month?
> Which search terms are wasting money?
> Run an account health check on account 1234567890
> What's my ROAS if I spent $5,000 and made $18,000?

Usage Examples

Once installed, type gemini to launch the interactive CLI. Here's what you can do:

Ask about your accounts (live API)

> List my Google Ads accounts
> Show campaign performance for account 1234567890 for the last 30 days
> What keywords have low quality scores?
> Show me device performance breakdown — mobile vs desktop
> Compare this month vs last month
> What changes were made to my account recently?

Find problems

> Run an account health check — flag anything critical
> Show me search terms with clicks but zero conversions
> Which campaigns are budget-limited?
> What's my impression share? How much traffic am I missing?

Make changes (live API — confirmation required)

> Pause campaign 123456789 on account 1234567890
> Enable that campaign again
> Update the daily budget to $75 for that campaign
> Change the CPC bid to $2.50 on ad group 987654321
> Add negative keywords "free, cheap, diy" to campaign 123456789
> Create a responsive search ad for ad group 987654321
> Apply that recommendation Google suggested

Do the math (no API credentials needed)

> I spend $75/day, CPC is $1.80, conversion rate is 3.5% — project my month
> Calculate my ROAS: $5,000 spend, $18,500 revenue
> What's my CPA if I spent $3,000 on 42 conversions?
> I have 60% impression share with 10,000 impressions — what am I missing?

Slash commands

/google-ads:analyze "Brand Search campaign last 30 days"
/google-ads:audit "full account, focus on wasted spend"
/google-ads:optimize "improve ROAS for ecommerce campaigns"

Switch themes

/theme google-ads          # Dark theme with Google's color palette
/theme google-ads-light    # Light theme matching Google Ads UI

What's Included

This extension implements every feature type in the Gemini CLI extension spec:

MCP Server — 22 Tools

Read Tools (15)

These tools query your Google Ads accounts:

Write Tools (7)

These tools make changes to your Google Ads account. Every write tool requires your explicit confirmation before executing.

Safety

• Read-only by default: run_gaql only allows SELECT queries — CREATE, UPDATE, DELETE, MUTATE, and REMOVE are all blocked
• Policy engine: Every API tool requires your confirmation before it runs
• Rate limiting: 10 calls per minute per tool to prevent runaway usage
• Error sanitization: Internal API details are never exposed — you get clean, actionable error messages
• Audit logging: Every tool call is logged to ~/.gemini/logs/google-ads-agent.log

Getting Credentials

You need 5 values from 3 places. This is a one-time setup.

From Google Ads (2 values)

1. Go to ads.google.com
2. Click Tools & Settings (wrench icon) → API Center
3. Copy your Developer Token
4. Note your Login Customer ID — this is your MCC (Manager) account ID, the 10-digit number at the top of the page (format: 123-456-7890)

Don't have API access? You'll need to apply for a developer token. Basic access is usually approved within a few days.

From Google Cloud Console (2 values)

1. Go to console.cloud.google.com
2. Create a project (or select an existing one)
3. Go to APIs & Services → Library → search for "Google Ads API" → Enable it
4. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
5. Choose Web application as the application type
6. Add https://developers.google.com/oauthplayground as an authorized redirect URI
7. Copy your Client ID and Client Secret

From OAuth Playground (1 value)

1. Go to developers.google.com/oauthplayground
2. Click the gear icon (top right) → check Use your own OAuth credentials
3. Paste your Client ID and Client Secret from the previous step
4. In the left panel, find Google Ads API v22 → select https://www.googleapis.com/auth/adwords
5. Click Authorize APIs → sign in with the Google account that has access to your Google Ads
6. Click Exchange authorization code for tokens
7. Copy the Refresh Token

Enter your credentials

gemini extensions config google-ads-agent

It will prompt for each value. Sensitive fields (developer token, client secret, refresh token) are stored in your system keychain — not in plain text.

Commands

Three slash commands for structured analysis:

# Deep-dive into a specific campaign or metric
/google-ads:analyze "Brand Search campaign performance last 30 days"

# Structured audit across 7 dimensions
/google-ads:audit "Acme Corp, focus on wasted spend and quality scores"

# Prioritized optimization recommendations
/google-ads:optimize "Improve ROAS for ecommerce campaigns"

Skills

Google Ads Agent

Activates automatically when you ask about campaigns, budgets, keywords, ads, PPC, ROAS, bidding, or Performance Max. Includes:

• GAQL query templates for common reports
• Cost formatting (Google uses micros — the skill converts to dollars)
• Anomaly detection thresholds (CPA spikes >20%, zero conversions, budget limits)
• Write safety protocol: Confirm → Execute → Post-check

Security Auditor

Activates when you ask to audit security, scan for secrets, or check for vulnerabilities. Includes:

• 10+ secret patterns (sk-, AIzaSy, ghp_, AKIA, xox, whsec_, etc.)
• Auth/authz, input validation, error handling, encryption checks
• Severity framework (Critical / High / Medium / Low)

Extension Structure

google-ads-gemini-extension/
├── gemini-extension.json       # Manifest — MCP server, settings, themes
├── GEMINI.md                   # Persistent context (loaded every session)
├── package.json                # Node.js dependencies
├── server.js                   # MCP server — 22 Google Ads API tools (15 read + 7 write)
├── commands/
│   └── google-ads/
│       ├── analyze.toml        # /google-ads:analyze
│       ├── audit.toml          # /google-ads:audit
│       └── optimize.toml       # /google-ads:optimize
├── skills/
│   ├── google-ads-agent/
│   │   └── SKILL.md            # PPC management expertise
│   └── security-auditor/
│       └── SKILL.md            # Security vulnerability scanning
├── hooks/
│   ├── hooks.json              # GAQL validation + audit logging
│   └── log-tool-call.js        # Audit trail logger
├── policies/
│   └── safety.toml             # User confirmation rules for all 22 tools (write tools at higher priority)
├── LICENSE
└── README.md

Update

gemini extensions update google-ads-agent

Uninstall

gemini extensions uninstall google-ads-agent

Local Development

git clone https://github.com/itallstartedwithaidea/google-ads-gemini-extension.git
cd google-ads-gemini-extension
npm install
gemini extensions link .

Changes auto-reload — no need to reinstall.

Troubleshooting

Related

• google-ads-api-agent — Full Python agent with 28 API actions and 6 sub-agents
• googleadsagent.ai — Live production system (Buddy) on Cloudflare
• Gemini CLI Extension Docs
• Extension Gallery

License

MIT