Google Ads MCP server — query campaigns, keywords, assets & more via natural language.
Built with Bun + TypeScript. Works with Claude, Cursor, and any MCP client.
---
## 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
```
Alternative: standalone binary
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"
```
### 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`:
Using npx (auto-updates)
```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"
}
}
}
}
```
Using binary (macOS / Linux)
```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"
}
}
}
}
```
Using binary (Windows)
```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"
}
}
}
}
```
## 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