# Google Ads MCP Server

MCP server for Google Ads campaign reporting and management via Claude.

## Setup

### 1. Google Cloud Console

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or select existing)
3. Enable the **Google Ads API**
4. Go to **APIs & Services > Credentials**
5. Create an **OAuth 2.0 Client ID** (type: Desktop app)
6. Note your **Client ID** and **Client Secret**

### 2. Developer Token

1. Sign in to your Google Ads account
2. Go to **Tools & Settings > API Center** (`ads.google.com/aw/apicenter`)
3. Apply for a developer token (test accounts get one immediately)
4. Note your **Developer Token**

### 3. OAuth Refresh Token

```bash
# Set your credentials first
export GOOGLE_ADS_CLIENT_ID=your_client_id
export GOOGLE_ADS_CLIENT_SECRET=your_client_secret

# Run the auth setup
npm run auth
```

This opens a browser for Google sign-in. After authorizing, you'll get a refresh token.

### 4. Find Your Customer ID

Your Google Ads Customer ID is the 10-digit number shown in the top-right of the Google Ads UI (e.g., `123-456-7890`). Enter it without dashes: `1234567890`.

### 5. Configure in Claude Code

Add to your Claude Code settings (`~/.claude/settings.local.json` or project-level):

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "node",
      "args": ["/path/to/google-ads-mcp/dist/index.js"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_developer_token",
        "GOOGLE_ADS_CLIENT_ID": "your_client_id",
        "GOOGLE_ADS_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your_refresh_token",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890"
      }
    }
  }
}
```

### Manager Account (MCC)

If your refresh token is from a Manager Account that manages the target account, add:

```json
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "your_manager_account_id"
```

## Tools (14 total)

### Reporting (8 tools)
- **gads_query** - Execute custom GAQL queries
- **gads_campaign_performance** - Campaign metrics with date range and status filters
- **gads_adgroup_performance** - Ad group metrics, filterable by campaign
- **gads_keyword_performance** - Keyword metrics with quality score
- **gads_ad_performance** - Ad-level metrics with headlines/descriptions
- **gads_search_terms** - Search terms that triggered ads
- **gads_account_summary** - High-level account overview
- **gads_budget_report** - Budget utilization per campaign

### Accounts (1 tool)
- **gads_list_accounts** - List accessible customer accounts

### Management (5 tools)
- **gads_list_campaigns** - List campaigns with configuration
- **gads_set_campaign_status** - Enable or pause a campaign
- **gads_update_campaign_budget** - Update daily budget
- **gads_set_adgroup_status** - Enable or pause an ad group
- **gads_set_keyword_status** - Enable, pause, or remove a keyword

## Build

```bash
npm install
npm run build
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GOOGLE_ADS_DEVELOPER_TOKEN` | Yes | From Google Ads API Center |
| `GOOGLE_ADS_CLIENT_ID` | Yes | OAuth2 client ID |
| `GOOGLE_ADS_CLIENT_SECRET` | Yes | OAuth2 client secret |
| `GOOGLE_ADS_REFRESH_TOKEN` | Yes | From `npm run auth` |
| `GOOGLE_ADS_CUSTOMER_ID` | Yes | 10-digit account ID (no dashes) |
| `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | No | Required if using Manager Account |