# Install globally (recommended for CLI usage)
npm install -g @hapotech/google-ads-mcp

# Or use with npx (no installation required)
npx @hapotech/google-ads-mcp

{
  "mcpServers": {
    "google-ads": {
      "command": "npx",
      "args": ["@hapotech/google-ads-mcp"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_ADS_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "123-456-7890"
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "google-ads": {
        "command": "npx",
        "args": ["@hapotech/google-ads-mcp"],
        "env": {
          "GOOGLE_ADS_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
          "GOOGLE_ADS_CLIENT_SECRET": "your-client-secret",
          "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
          "GOOGLE_ADS_DEVELOPER_TOKEN": "your-developer-token",
          "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "123-456-7890"
        }
      }
    }
  }
}

# Required for OAuth (Recommended Method)
GOOGLE_ADS_CLIENT_ID="123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com"
GOOGLE_ADS_CLIENT_SECRET="GOCSPX-AbCdEfGhIjKlMnOpQrStUvWxYz"
GOOGLE_ADS_REFRESH_TOKEN="1//04AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIjKlMnOpQrStUvWxYz"
GOOGLE_ADS_DEVELOPER_TOKEN="AbCdEfGhIjKlMnOpQrStUvWxYz"

# Optional: For manager accounts managing multiple clients
GOOGLE_ADS_LOGIN_CUSTOMER_ID="123-456-7890"

# Alternative: Service Account (Advanced)
GOOGLE_ADS_SERVICE_ACCOUNT_KEY_PATH="/path/to/service-account.json"
GOOGLE_ADS_DEVELOPER_TOKEN="AbCdEfGhIjKlMnOpQrStUvWxYz"

You: "Show me all campaigns for account 1234567890 with their performance metrics"

Claude: I'll get your campaigns and their performance data.
[Uses get_campaigns and get_campaign_performance tools]

Results:
• Campaign "Holiday Sale 2024": 15,432 impressions, 1,234 clicks (8.0% CTR)
• Campaign "Brand Awareness": 8,901 impressions, 456 clicks (5.1% CTR)
• Total spend: $2,847.32 this month

You: "Create a search campaign called 'New Product Launch' with $100 daily budget for account 1234567890"

Claude: I'll create a new search campaign for you. For safety, it will be created in PAUSED state.
[Uses create_campaign tool]

✅ Campaign created successfully!
• Name: "New Product Launch"
• Budget: $100/day
• Status: PAUSED (ready for you to review and enable)
• Campaign ID: 987654321

You: "What are the top performing keywords for campaign 987654321?"

Claude: I'll analyze the keyword performance for that campaign.
[Uses execute_gaql_query tool with custom GAQL]

Top performing keywords:
1. "premium software solution" - 2,341 impressions, 187 clicks (8.0% CTR)
2. "best project management" - 1,876 impressions, 134 clicks (7.1% CTR)
3. "business automation tool" - 1,432 impressions, 89 clicks (6.2% CTR)

You: "Show me a summary of all my client accounts' performance this month"

Claude: I'll get performance data across all your managed accounts.
[Uses list_accounts and get_campaign_performance for each]

Account Performance Summary:
📊 Client A (Account: 1111111111): $12,340 spent, 234 conversions
📊 Client B (Account: 2222222222): $8,750 spent, 156 conversions
📊 Client C (Account: 3333333333): $15,680 spent, 289 conversions
📈 Total: $36,770 spent, 679 conversions across all accounts

SELECT
  campaign.name,
  campaign.status,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY metrics.cost_micros DESC

SELECT
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  ad_group_criterion.quality_info.quality_score,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc
FROM ad_group_criterion
WHERE ad_group_criterion.type = 'KEYWORD'
  AND segments.date DURING LAST_7_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.ctr DESC

SELECT
  ad_group_ad.ad.responsive_search_ad.headlines,
  ad_group_ad.ad.responsive_search_ad.descriptions,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.conversions
FROM ad_group_ad
WHERE ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD'
  AND segments.date DURING LAST_14_DAYS
  AND metrics.impressions > 1000
ORDER BY metrics.conversions DESC

-- Get campaign performance
SELECT
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

-- Get keyword performance
SELECT
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  metrics.impressions,
  metrics.clicks
FROM ad_group_criterion
WHERE ad_group_criterion.type = 'KEYWORD'
  AND segments.date DURING LAST_7_DAYS

graph TD
    A[Claude AI] --> B[MCP Protocol]
    B --> C[Google Ads MCP Server]
    C --> D[Authentication Manager]
    C --> E[Google Ads API Client]
    D --> F[OAuth 2.0]
    D --> G[Service Account]
    E --> H[Google Ads API v19]

    C --> I[82 Available Tools]
    I --> J[Read Operations]
    I --> K[Write Operations]

    J --> L[Campaigns, Ads, Keywords]
    K --> M[Create, Update, Manage]

# Clone and setup
git clone https://github.com/anegash/google-ads-mcp-server.git
cd google-ads-mcp-server

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your credentials

# Development mode
npm run dev

# Build
npm run build

# Test
npm test

src/
├── api/
│   └── client.ts          # Google Ads API client with 82 tools
├── auth/
│   └── credentials.ts     # Authentication management
├── types/
│   ├── index.ts          # Main type exports
│   ├── conversions.ts    # Conversion tracking types
│   ├── audiences.ts      # Audience management types
│   ├── reporting.ts      # Enhanced reporting types
│   ├── budgets.ts        # Budget & bidding types
│   ├── assets.ts         # Asset management types
│   ├── campaigns.ts      # Advanced campaign types
│   ├── targeting.ts      # Geographic & demographic types
│   ├── extensions.ts     # Extensions & recommendations
│   └── management.ts     # Organization & management types
├── server.ts             # MCP server with all 82 tools
├── cli.ts                # Command-line interface
└── index.ts              # Package exports

npx @hapotech/google-ads-mcp --help

Options:
  -c, --config                    Path to config file
  --client-id                     Google Ads Client ID
  --client-secret                 Google Ads Client Secret
  --refresh-token                 Google Ads Refresh Token
  --developer-token               Google Ads Developer Token
  --login-customer-id             Google Ads Login Customer ID
  --service-account-key-path      Path to service account key file
  --use-keyword-sandbox           Use keyword planning sandbox
  --help                          Show help

# Set log level
export LOG_LEVEL=debug

# Enable debug output
export DEBUG=google-ads-mcp:*

✅ Solutions:
• Verify your developer token is approved and active
• Check OAuth credentials (client ID, client secret, refresh token)
• Ensure the refresh token hasn't expired
• Verify Google Ads API is enabled in Google Cloud Console

✅ Solutions:
• Check if you have access to the customer account
• Verify GOOGLE_ADS_LOGIN_CUSTOMER_ID is set for manager accounts
• Ensure your developer token has the necessary permissions
• Check if the account is properly linked in Google Ads

✅ Solutions:
• Set GOOGLE_ADS_LOGIN_CUSTOMER_ID to your manager account ID
• Verify the managed account is linked under your manager account
• Check account permissions in Google Ads → Account Management
• Ensure the managed account accepted your invitation

✅ Solutions:
• Google Ads API has daily and per-minute quotas
• Implement delays between requests
• Monitor usage in Google Cloud Console → APIs & Services → Quotas
• Contact Google support for quota increases if needed

✅ Solutions:
• Restart Claude Desktop after configuration changes
• Verify .mcp.json or claude_desktop_config.json syntax
• Check file permissions and paths
• Ensure npx can access @hapotech/google-ads-mcp

✅ Solutions:
• Use absolute paths for service account keys
• Quote environment variables with special characters
• Restart the application after setting environment variables
• Check that variable names match exactly (case-sensitive)

# For CLI usage
DEBUG=google-ads-mcp:* npx @hapotech/google-ads-mcp

# For environment
export DEBUG=google-ads-mcp:*
export LOG_LEVEL=debug

# Test authentication
npx @hapotech/google-ads-mcp --test-auth

# Validate configuration
npx @hapotech/google-ads-mcp --validate-config

# List available accounts (requires working auth)
npx @hapotech/google-ads-mcp --list-accounts

# Test the complete toolset
npx @hapotech/google-ads-mcp

# Try advanced conversions
"Show me conversion attribution for account 1234567890"

# Create custom audiences
"Create a customer match list for my email database"

# Generate comprehensive reports
"Give me a complete performance analysis across all campaigns"