Meta Agent Tools
PT

Back to the catalog

io.github.pijusz/mcp-gads

Google Ads MCP server — query campaigns, keywords, assets & more via natural language

Open source Open in the app JSON README (API)

About

Google Ads MCP server — query campaigns, keywords, assets & more via natural language

Details

Kind
MCP servers
Topic
Marketing & analytics
Publisher
pijusz
Origin
official
Category
ferramentas
Transport
local
Version
0.5.4
Stars
1
Last push
2026-07-31T13:24:27Z
Repository state
ativo
Language
TypeScript
License
MIT
Added
2026-08-29 04:01:01
Updated
2026-08-29 04:01:01
Origin id
io.github.pijusz/mcp-gads

README

<p align="center">
  <img src="logo.svg" alt="mcp-gads" width="280" />
</p>

<p align="center">
  Google Ads MCP server — query campaigns, keywords, assets & more via natural language.
  <br/>
  Built with Bun + TypeScript. Works with Claude, Cursor, and any MCP client.
</p>

---

## Quick Start

### 1. Get Credentials

You need a [Google Ads API developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token) and OAuth client credentials.

1. Download your OAuth client JSON from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Set environment variables:

```bash
export GOOGLE_ADS_DEVELOPER_TOKEN=your-token
export GOOGLE_ADS_CREDENTIALS_PATH=./credentials.json
```

3. Run the setup helper to authorize:

```bash
npx mcp-gads setup
```

This opens your browser, completes OAuth, and saves a refresh token.

### 2. Add to Claude Code

```bash
claude mcp add google-ads --scope user --transport stdio \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \
  -- npx -y mcp-gads@latest
```

That's it. Restart Claude Code and the tools are available. Every session runs the latest version automatically.

> Also works with `bunx mcp-gads@latest` if you have [Bun](https://bun.sh/).
> Requires Node 22+ when running via `npx`.

If your environment blocks npm registry access at runtime, install once and run the published binary name directly:

```bash
npm i -g mcp-gads@latest
claude mcp add google-ads --scope user --transport stdio \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \
  -- mcp-gads
```

<details>
<summary>Alternative: standalone binary</summary>

Download a pre-built binary from [Releases](https://github.com/pijusz/mcp-gads/releases):

| Platform | File |
|----------|------|
| macOS (Apple Silicon) | `mcp-gads-darwin-arm64` |
| macOS (Intel) | `mcp-gads-darwin-x64` |
| Linux | `mcp-gads-linux-x64` |
| Windows | `mcp-gads-windows-x64.exe` |

**macOS / Linux:**

```bash
curl -Lo mcp-gads https://github.com/pijusz/mcp-gads/releases/latest/download/mcp-gads-darwin-arm64
chmod +x mcp-gads
sudo mv mcp-gads /usr/local/bin/
claude mcp add google-ads --scope user --transport stdio \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token \
  -e GOOGLE_ADS_CREDENTIALS_PATH=/path/to/credentials.json \
  -- /usr/local/bin/mcp-gads
```

**Windows (PowerShell):**

```powershell
Invoke-WebRequest -Uri "https://github.com/pijusz/mcp-gads/releases/latest/download/mcp-gads-windows-x64.exe" -OutFile "$env:LOCALAPPDATA\mcp-gads.exe"
claude mcp add google-ads --scope user --transport stdio -e GOOGLE_ADS_DEVELOPER_TOKEN=your-token -e GOOGLE_ADS_CREDENTIALS_PATH=C:\path\to\credentials.json -- "%LOCALAPPDATA%\mcp-gads.exe"
```

</details>

### ChatGPT Codex

Codex uses TOML, not JSON. Install once, then add to `~/.codex/config.toml`:

```bash
npm i -g mcp-gads
```

```toml
[mcp_servers.gads]
command = "mcp-gads"

[mcp_servers.gads.env]
GOOGLE_ADS_DEVELOPER_TOKEN = "your-token"
GOOGLE_ADS_CREDENTIALS_PATH = "/absolute/path/to/credentials.json"
```

Three gotchas that cause silent failures on Codex:

- **Don't use `npx -y` without raising the timeout.** Codex's default `startup_timeout_sec` is 10s, which is too short for npx's first-run download. A global install (above) or the [prebuilt binary](#quick-start) sidesteps this entirely. If you must use npx, add `startup_timeout_sec = 30`.
- **Env vars must go under `[mcp_servers.gads.env]`.** Codex does not inherit the parent shell environment into stdio servers — exporting vars in your shell won't reach the server.
- **Use absolute paths** for `GOOGLE_ADS_CREDENTIALS_PATH`. Codex spawns the server with its own cwd, so relative paths silently miss.

On Windows some Codex versions use `startup_timeout_ms = 20000` instead of `_sec`.

### Claude Desktop

Add to your `claude_desktop_config.json`:

<details>
<summary>Using npx (auto-updates)</summary>

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["-y", "mcp-gads@latest"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/path/to/credentials.json"
      }
    }
  }
}
```

</details>

<details>
<summary>Using binary (macOS / Linux)</summary>

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "/usr/local/bin/mcp-gads",
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/path/to/credentials.json"
      }
    }
  }
}
```

</details>

<details>
<summary>Using binary (Windows)</summary>

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "C:\\Users\\YOU\\AppData\\Local\\mcp-gads.exe",
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
        "GOOGLE_ADS_CREDENTIALS_PATH": "C:\\path\\to\\credentials.json"
      }
    }
  }
}
```

</details>

## Tools (39)

### Account Management
| Tool | Description |
|------|-------------|
| `list_accounts` | List all accessible Google Ads accounts |
| `get_account_currency` | Get the currency code for an account |
| `get_account_hierarchy` | Get MCC account tree (manager -> client) |

### Queries
| Tool | Description |
|------|-------------|
| `execute_gaql_query` | Run any GAQL query (table output) |
| `run_gaql` | Run GAQL with format options (table/json/csv) |
| `get_gaql_help` | GAQL reference guide with syntax, resources, and examples |
| `list_resources` | List valid GAQL FROM clause resources |

### Campaigns
| Tool | Description |
|------|-------------|
| `get_campaign_performance` | Campaign metrics (impressions, clicks, cost, conversions) |
| `get_budget_utilization` | Budget amounts vs actual spend |

### Ads
| Tool | Description |
|------|-------------|
| `get_ad_performance` | Ad-level performance metrics |
| `get_ad_creatives` | RSA headlines, descriptions, final URLs |

### Assets
| Tool | Description |
|------|-------------|
| `get_image_assets` | List image assets with URLs and dimensions |
| `download_image_asset` | Download a specific image asset to disk |
| `get_asset_usage` | Find where assets are used (campaigns, ad groups) |
| `analyze_image_assets` | Image asset performance with metrics |

### Keywords
| Tool | Description |
|------|-------------|
| `generate_keyword_ideas` | Keyword Planner suggestions from seed keywords |
| `get_keyword_volumes` | Historical search volume for specific keywords |
| `get_quality_scores` | Quality scores with component breakdown |
| `get_search_terms` | Actual search queries triggering your ads |
| `get_paid_organic_search_terms` | Paid vs organic clicks per query (needs Search Console link) |
| `get_search_term_insights` | Search demand categories — the only view into Performance Max & Demand Gen queries |

### Geographic & Device
| Tool | Description |
|------|-------------|
| `get_geographic_performance` | Performance by location |
| `get_device_performance` | Performance by device type |

### Insights
| Tool | Description |
|------|-------------|
| `get_recommendations` | Google's AI optimization suggestions |
| `get_change_history` | Recent account changes |

### Extended Reporting

| Tool | Description |
|------|-------------|
| `get_ad_group_performance` | Ad group metrics with optional campaign filter |
| `get_conversion_actions` | Conversion actions with settings and performance |
| `get_account_summary` | Quick dashboard: totals + top 5 campaigns |
| `get_impression_share` | Competitive position: impression share and lost IS |
| `get_ad_schedule_performance` | Performance by hour or day of week |
| `get_audience_performance` | Demographics: age range and gender breakdowns |
| `get_landing_page_performance` | Landing page URLs with metrics |
| `get_placement_performance` | Display/PMax placement details |
| `get_asset_group_performance` | PMax asset group metrics and ad strength |
| `get_video_performance` | YouTube/video view rates and quartile completion |
| `get_labels` | Labels and their campaign/ad group assignments |

### Write Tools (disabled by default)
Enable with `GOOGLE_ADS_ENABLE_MUTATIONS=true`:

| Tool | Description |
|------|-------------|
| `update_campaign_status` | Pause/enable a campaign |
| `update_ad_group_status` | Pause/enable an ad group |
| `update_ad_status` | Pause/enable an ad |
| `update_campaign_budget` | Change daily budget amount |
| `add_negative_keywords` | Add negative keywords to a campaign |

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GOOGLE_ADS_DEVELOPER_TOKEN` | Yes | — | API developer token |
| `GOOGLE_ADS_CREDENTIALS_PATH` | Yes | — | Path to OAuth client JSON |
| `GOOGLE_ADS_AUTH_TYPE` | No | `oauth` | `oauth` or `service_account` |
| `GOOGLE_ADS_CUSTOMER_ID` | No | — | Default customer ID (skips passing it per tool) |
| `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | No | — | MCC manager account ID |
| `GOOGLE_ADS_IMPERSONATION_EMAIL` | No | — | Service account impersonation email |
| `GOOGLE_ADS_ENABLE_MUTATIONS` | No | `false` | Enable write tools |
| `GOOGLE_ADS_ENV_FILE` | No | `.env` | Path to .env file (loaded if present, never overrides existing env) |
| `GOOGLE_ADS_API_VERSION` | No | `v25` | Google Ads API version |

## Updates

**Using `npx @latest`** (recommended): You always get the latest version — no manual updates needed.

**Using a binary**: The server checks for new releases on startup and logs to stderr if outdated:

```
[mcp-gads] v0.2.0 available (current: v0.1.0). Download: https://github.com/pijusz/mcp-gads/releases/latest
```

Check your installed version:

```bash
mcp-gads --version
```

To update, download the new binary and replace the old one.

## Development

Requires [Bun](https://bun.sh/).

```bash
git clone https://github.com/pijusz/mcp-gads.git
cd mcp-gads
bun install
bun test           # tests
bun run build      # standalone binary
bun run inspect    # MCP Inspector
bun run check      # biome format + lint
```

## License

MIT

More