# Google Ads MCP Server

Servidor MCP completo para gerenciamento do Google Ads com CRUD total, dashboard de visualização, relatórios e gestão de todas as funcionalidades disponíveis no painel do Google Ads.

## Funcionalidades (85+ ferramentas)

### Contas & Clientes
- `list_accessible_customers` — Listar contas acessíveis
- `get_customer_details` — Detalhes da conta
- `list_customer_clients` — Clientes sob MCC
- `update_customer` — Atualizar configurações
- `get_account_hierarchy` — Hierarquia de contas
- `get_change_history` — Histórico de alterações

### Campanhas (CRUD Completo)
- `list_campaigns` — Listar campanhas com filtros
- `get_campaign` — Detalhes completos da campanha
- `create_campaign` — Criar campanha (Search, Display, Shopping, Video, Performance Max, etc.)
- `update_campaign` — Atualizar nome, status, lances, datas
- `remove_campaign` — Remover campanha
- `get_campaign_performance` — Métricas de performance
- `copy_campaign` — Copiar configurações de campanha

### Grupos de Anúncios (CRUD Completo)
- `list_ad_groups` — Listar grupos de anúncios
- `get_ad_group` — Detalhes do grupo
- `create_ad_group` — Criar grupo de anúncios
- `update_ad_group` — Atualizar configurações
- `remove_ad_group` — Remover grupo
- `get_ad_group_performance` — Métricas de performance

### Anúncios (CRUD Completo)
- `list_ads` — Listar anúncios
- `get_ad` — Detalhes do anúncio
- `create_responsive_search_ad` — Criar RSA com headlines e descriptions
- `update_ad_status` — Ativar/pausar anúncio
- `remove_ad` — Remover anúncio
- `get_ad_performance` — Métricas de performance

### Palavras-chave (CRUD Completo)
- `list_keywords` — Listar keywords com quality score
- `add_keywords` — Adicionar keywords (Exact, Phrase, Broad)
- `update_keyword` — Atualizar lance, status, URLs
- `remove_keyword` — Remover keyword
- `get_keyword_performance` — Performance com impression share
- `get_search_terms` — Relatório de termos de pesquisa
- `add_negative_keywords` — Adicionar negativos (campanha ou grupo)

### Orçamentos & Estratégias de Lances
- `list_budgets` — Listar orçamentos
- `create_budget` — Criar orçamento
- `update_budget` — Atualizar valor/método de entrega
- `remove_budget` — Remover orçamento
- `list_bidding_strategies` — Listar estratégias
- `create_bidding_strategy` — Criar estratégia (Target CPA, Target ROAS, etc.)
- `update_bidding_strategy` — Atualizar estratégia
- `remove_bidding_strategy` — Remover estratégia

### Audiências & Segmentação
- `list_audiences` — Listar audiências/user lists
- `get_audience_performance` — Performance de audiências
- `list_campaign_targeting` — Critérios de segmentação
- `add_campaign_location_targeting` — Segmentação geográfica
- `add_campaign_language_targeting` — Segmentação por idioma
- `add_ad_schedule` — Programação de anúncios (dayparting)
- `remove_campaign_criterion` — Remover critério
- `get_geo_target_constants` — Buscar constantes geográficas
- `get_demographics_performance` — Performance demográfica

### Assets & Extensões
- `list_assets` — Listar todos os assets
- `create_sitelink_asset` — Criar sitelink
- `create_callout_asset` — Criar callout
- `create_structured_snippet_asset` — Criar snippets estruturados
- `create_call_asset` — Criar extensão de chamada
- `create_price_asset` — Criar extensão de preço
- `create_promotion_asset` — Criar extensão de promoção
- `create_lead_form_asset` — Criar formulário de lead
- `link_asset_to_campaign` — Vincular asset à campanha
- `link_asset_to_ad_group` — Vincular asset ao grupo
- `remove_asset` — Remover asset
- `get_asset_performance` — Performance de assets
- `list_campaign_assets` — Assets de uma campanha
- `remove_campaign_asset` — Desvincular asset

### Conversões
- `list_conversion_actions` — Listar ações de conversão
- `get_conversion_action` — Detalhes da conversão
- `create_conversion_action` — Criar ação de conversão
- `update_conversion_action` — Atualizar conversão
- `remove_conversion_action` — Remover conversão
- `get_conversion_performance` — Performance de conversões

### Relatórios & Dashboard
- `execute_gaql_query` — Executar consulta GAQL personalizada
- `get_account_dashboard` — Dashboard completo da conta
- `get_campaign_dashboard` — Dashboard detalhado de campanha
- `get_performance_by_device` — Performance por dispositivo
- `get_performance_by_network` — Performance por rede
- `get_performance_by_hour` — Performance por hora
- `get_performance_by_day_of_week` — Performance por dia da semana
- `get_geographic_performance` — Performance geográfica
- `get_landing_page_performance` — Performance de landing pages
- `compare_date_ranges` — Comparar períodos

### Labels & Conjuntos Compartilhados
- `list_labels` — Listar labels
- `create_label` — Criar label
- `remove_label` — Remover label
- `apply_label_to_campaign` — Aplicar label à campanha
- `apply_label_to_ad_group` — Aplicar label ao grupo
- `list_shared_sets` — Listar listas compartilhadas
- `create_shared_set` — Criar lista de negativos compartilhada
- `add_shared_set_criteria` — Adicionar termos à lista
- `link_shared_set_to_campaign` — Vincular lista à campanha

### Recomendações & Otimização
- `list_recommendations` — Listar recomendações do Google
- `apply_recommendation` — Aplicar recomendação
- `dismiss_recommendation` — Ignorar recomendação
- `get_optimization_score` — Score de otimização

### Experimentos & Alterações
- `list_experiments` — Listar testes A/B
- `list_experiment_arms` — Listar variantes
- `get_change_status` — Alterações recentes

## Pré-requisitos

1. **Google Cloud Project** com a Google Ads API habilitada
2. **OAuth2 Client ID** tipo Desktop
3. **Developer Token** do Google Ads (obtido em ads.google.com > API Center)
4. **Node.js** >= 18

## Instalação

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

## Configuração

### Opção 1: Variáveis de ambiente

```bash
export GOOGLE_ADS_CLIENT_ID="seu-client-id"
export GOOGLE_ADS_CLIENT_SECRET="seu-client-secret"
export GOOGLE_ADS_DEVELOPER_TOKEN="seu-developer-token"
export GOOGLE_ADS_REFRESH_TOKEN="seu-refresh-token"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="123-456-7890"  # opcional, para contas MCC
```

### Opção 2: Setup interativo

```bash
npm run auth
```

Isso criará um arquivo de credenciais em `~/.google-ads-mcp/credentials.json`.

## Configuração no Claude Code

Adicione ao seu `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "google-ads": {
      "command": "node",
      "args": ["/caminho/para/google-ads-manager-hub/dist/index.js"],
      "env": {
        "GOOGLE_ADS_CLIENT_ID": "seu-client-id",
        "GOOGLE_ADS_CLIENT_SECRET": "seu-client-secret",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "seu-developer-token",
        "GOOGLE_ADS_REFRESH_TOKEN": "seu-refresh-token",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890"
      }
    }
  }
}
```

## Uso

Após configurar, todas as ferramentas ficam disponíveis via MCP. Exemplos:

- "Liste todas as minhas campanhas ativas"
- "Crie uma campanha de Search com orçamento de R$50/dia"
- "Mostre o dashboard de performance dos últimos 30 dias"
- "Adicione estas keywords ao grupo de anúncios X: ..."
- "Pause a campanha Y"
- "Mostre o relatório de termos de pesquisa"
- "Quais são as recomendações do Google para minha conta?"

## API Version

Este servidor usa a **Google Ads API v23** (mais recente, lançada em Janeiro 2026).

## Estrutura do Projeto

```
src/
├── index.ts                    # Entry point - MCP server
├── auth/
│   ├── oauth2.ts               # OAuth2 client + token management
│   └── setup.ts                # Interactive auth setup CLI
├── client/
│   └── google-ads-client.ts    # Google Ads REST API client
└── tools/
    ├── accounts/               # Account & customer management
    ├── campaigns/              # Campaign CRUD
    ├── adgroups/               # Ad group CRUD
    ├── ads/                    # Ad CRUD (RSA, etc.)
    ├── keywords/               # Keywords + search terms + negatives
    ├── budgets/                # Budgets + bidding strategies
    ├── audiences/              # Audiences + targeting + demographics
    ├── assets/                 # Assets (sitelinks, callouts, etc.)
    ├── conversions/            # Conversion actions + tracking
    ├── reporting/              # Dashboard + GAQL + analytics
    ├── labels/                 # Labels + shared sets
    ├── recommendations/        # Optimization recommendations
    ├── experiments/            # A/B tests + change tracking
    └── extensions/             # Price, promotion, lead form extensions
```