Google Ads MCP Server 🚀

Server MCP (Model Context Protocol) per l'integrazione con Google Ads API - Ottimizzato per Trae.ai

Connetti Google Ads API direttamente a Trae.ai e altri client MCP con autenticazione OAuth 2.0, refresh automatico dei token, query GAQL e ricerca keyword.

📦 Installazione

Installazione via NPM (Consigliata)

Installazione Globale

# Installa globalmente per usare il comando 'google-ads-mcp' ovunque
npm install [email protected]

Installazione Locale

# Installa nel progetto corrente
npm install [email protected]

✅ Novità v1.0.6: Documentazione completa con soluzioni a tutti gli errori comuni! ✅ Novità v1.0.5: Le dipendenze Python vengono installate automaticamente durante l'installazione NPM!

Verifica Installazione

# Verifica che il pacchetto sia installato correttamente
npm list google-ads-mcp-server

# Per installazione globale, verifica il comando
google-ads-mcp --help

Installazione Manuale (Solo per sviluppo)

# Clona il repository
git clone https://github.com/your-repo/google-ads-mcp-server.git
cd google-ads-mcp-server

# Installa le dipendenze Python
pip install -r requirements.txt

# Esegui il setup
python setup.py

✨ Funzionalità

• 🔐 Autenticazione OAuth 2.0 - Autenticazione browser one-time con refresh automatico
• 🔄 Gestione Token Intelligente - Gestisce automaticamente i token scaduti
• 📊 Esecuzione Query GAQL - Esegui qualsiasi query Google Ads Query Language
• 🏢 Gestione Account - Elenca e gestisci account Google Ads
• 🔍 Ricerca Keyword - Genera idee keyword con dati di volume di ricerca
• 🚀 Ottimizzato per Trae.ai - Configurazione semplificata per Trae.ai
• 🛡️ Storage Locale Sicuro - Token memorizzati localmente, mai esposti

📋 Strumenti Disponibili

| Strumento | Descrizione | Parametri | Esempio d'uso | |-----------|-------------|-----------|---------------| | list_accounts | Elenca tutti gli account Google Ads accessibili | Nessuno | "Elenca tutti i miei account Google Ads" | | run_gaql | Esegue query GAQL con formattazione personalizzata | customer_id, query, manager_id (opzionale) | "Mostra le performance delle campagne per l'account 1234567890" | | run_keyword_planner | Genera idee keyword con metriche | customer_id, keywords, manager_id, page_url, opzioni date | "Genera idee keyword per 'digital marketing'" |

Nota: Tutti gli strumenti gestiscono automaticamente l'autenticazione - nessun parametro token richiesto!

🚀 Setup Rapido per Trae.ai

Prerequisiti

Prima di configurare il server MCP, avrai bisogno di:

• Python 3.10+ installato
• Un account Google Cloud Platform
• Un account Google Ads con accesso API

1. Setup Google Cloud Platform

1.1 Crea Progetto Google Cloud

1. Vai su Google Cloud Console
2. Crea un nuovo progetto:
   • Clicca "Seleziona un progetto" → "Nuovo Progetto"
   • Inserisci nome progetto (es. "Google Ads MCP")
   • Clicca "Crea"

1.2 Abilita Google Ads API

1. Nella Google Cloud Console:
   • Vai su "API e servizi" → "Libreria"
   • Cerca "Google Ads API"
   • Clicca e premi "Abilita"

1.3 Crea Credenziali OAuth 2.0

1. Vai su "API e servizi" → "Credenziali"
2. Clicca "+ CREA CREDENZIALI" → "ID client OAuth 2.0"
3. Configura schermata consenso (se prima volta):
   • Clicca "Configura schermata consenso"
   • Scegli "Esterno" (a meno che non hai Google Workspace)
   • Compila campi richiesti:
     • Nome app: "Google Ads MCP"
     • Email supporto utenti: La tua email
     • Contatto sviluppatore: La tua email
   • Clicca "Salva e continua" per tutti i passaggi
4. Crea Client OAuth:
   • Tipo applicazione: "Applicazione desktop"
   • Nome: "Google Ads MCP Client"
   • Clicca "Crea"
5. Scarica credenziali:
   • Clicca pulsante "Scarica JSON"
   • Salva file come client_secret_[stringa-lunga].json nella directory del progetto

2. Setup Google Ads API

2.1 Ottieni Developer Token

1. Accedi a Google Ads
2. Vai su Strumenti e impostazioni (icona chiave inglese nella navigazione superiore)
3. Sotto "Configurazione", clicca "Centro API"
4. Accetta Termini di Servizio se richiesto
5. Clicca "Richiedi token"
6. Compila modulo di richiesta:
   • Descrivi il tuo caso d'uso (es. "Integrazione MCP per analisi campagne")
   • Fornisci dettagli tecnici sulla tua implementazione
7. Invia e attendi approvazione (solitamente 1-3 giorni lavorativi)

Nota: Inizialmente riceverai un token di test con funzionalità limitate. Dopo i test, puoi richiedere l'accesso produzione.

3. Configurazione per Trae.ai

3.1 Setup Automatico (Consigliato)

Dopo aver installato il pacchetto NPM, esegui il setup automatico:

# Se installato globalmente
google-ads-mcp --setup

# Se installato localmente
npx google-ads-mcp-server --setup

# Oppure usa npm run
npm run setup

Il setup automatico:

1. ✅ Crea il file .env con le variabili necessarie
2. ✅ Configura automaticamente trae_config.json
3. ✅ Verifica le dipendenze Python
4. ✅ Fornisce istruzioni per Trae.ai

3.2 Configurazione Manuale Environment

Se preferisci configurare manualmente, crea un file .env:

# Richiesto: Google Ads API Developer Token
GOOGLE_ADS_DEVELOPER_TOKEN=il_tuo_developer_token_qui

# Richiesto: Percorso al file JSON credenziali OAuth
GOOGLE_ADS_OAUTH_CONFIG_PATH=/percorso/completo/al/client_secret_file.json

3.3 Configurazione Trae.ai

Per installazione NPM globale:

{
  "google-ads": {
    "command": "google-ads-mcp",
    "env": {
      "GOOGLE_ADS_DEVELOPER_TOKEN": "il_tuo_developer_token",
      "GOOGLE_ADS_OAUTH_CONFIG_PATH": "/percorso/completo/al/client_secret_file.json"
    }
  }
}

Per installazione NPM locale:

{
  "google-ads": {
    "command": "npx",
    "args": ["google-ads-mcp-server"],
    "cwd": "/percorso/alla/directory/del/progetto",
    "env": {
      "GOOGLE_ADS_DEVELOPER_TOKEN": "il_tuo_developer_token",
      "GOOGLE_ADS_OAUTH_CONFIG_PATH": "/percorso/completo/al/client_secret_file.json"
    }
  }
}

Per installazione manuale:

{
  "google-ads": {
    "command": "python",
    "args": ["server.py"],
    "cwd": "/percorso/alla/directory/del/progetto",
    "env": {
      "GOOGLE_ADS_DEVELOPER_TOKEN": "il_tuo_developer_token",
      "GOOGLE_ADS_OAUTH_CONFIG_PATH": "/percorso/completo/al/client_secret_file.json"
    }
  }
}

💡 Suggerimento: Usa il setup automatico per generare automaticamente la configurazione corretta!

3.4 Riavvia Trae.ai

Riavvia Trae.ai per caricare la nuova configurazione.

🔐 Prima Autenticazione

5.1 Attiva Flusso OAuth

1. Apri Trae.ai
2. Prova qualsiasi comando Google Ads, per esempio:

   "Elenca tutti i miei account Google Ads"

5.2 Completa Autenticazione

1. Il browser si apre automaticamente alla pagina OAuth di Google
2. Accedi con il tuo account Google (quello con accesso Google Ads)
3. Concedi permessi cliccando "Consenti"
4. Il browser mostra pagina di successo
5. Torna su Trae.ai - il tuo comando si completerà automaticamente!

5.3 Verifica Setup

Dopo l'autenticazione, dovresti vedere:

• Un file google_ads_token.json creato nella directory del progetto
• I tuoi account Google Ads elencati nella risposta di Trae.ai

📖 Esempi d'Uso

Operazioni Account Base

"Elenca tutti i miei account Google Ads"

"Mostra i dettagli dell'account e quali hanno campagne attive"

Analisi Campagne

"Mostra le performance delle campagne per l'account 1234567890 negli ultimi 30 giorni"

"Ottieni dati di conversione per tutte le campagne nell'ultima settimana"

"Quali campagne hanno il costo per conversione più alto?"

Ricerca Keyword

"Genera idee keyword per 'digital marketing' usando l'account 1234567890"

"Trova opportunità keyword per 'automazione AI' con dati di volume di ricerca"

"Ricerca keyword per la pagina https://example.com/servizi"

Query GAQL Personalizzate

"Esegui questa query GAQL per l'account 1234567890:
SELECT campaign.name, metrics.clicks, metrics.cost_micros 
FROM campaign 
WHERE segments.date DURING LAST_7_DAYS"

"Ottieni dati performance keyword:
SELECT ad_group_criterion.keyword.text, metrics.ctr, metrics.average_cpc
FROM keyword_view 
WHERE metrics.impressions > 100"

📁 Struttura Progetto

google-ads-mcp-server/
├── server.py                           # Server MCP principale
├── oauth/
│   ├── __init__.py                     # Inizializzazione package
│   └── google_auth.py                  # Logica autenticazione OAuth
├── google_ads_token.json               # Storage token auto-generato (gitignored)
├── client_secret_[stringa-lunga].json  # Tue credenziali OAuth (gitignored)
├── .env                                # Variabili ambiente (gitignored)
├── env.example                         # Template environment
├── requirements.txt                    # Dipendenze Python
├── package.json                        # Configurazione NPM
├── setup.py                            # Script setup automatico
├── trae_config.json                    # Configurazione Trae.ai
├── LICENSE                             # Licenza MIT
└── README.md                           # Questo file

🔒 Sicurezza e Best Practice

Sicurezza File

• ✅ File credenziali sono gitignored - Mai committati nel controllo versione
• ✅ Storage token locale - Token memorizzati in google_ads_token.json localmente
• ✅ Variabili ambiente - Dati sensibili nel file .env
• ✅ Refresh automatico - Tempo di esposizione token minimale

Permessi File Raccomandati

# Imposta permessi sicuri per file sensibili
chmod 600 .env
chmod 600 google_ads_token.json
chmod 600 client_secret_*.json

Considerazioni Produzione

1. Usa variabili ambiente invece di file .env in produzione
2. Implementa rate limiting per rispettare le quote API
3. Monitora uso API nella Google Cloud Console
4. Storage token sicuro con controlli accesso appropriati
5. Rotazione token regolare per sicurezza migliorata

🛠️ Risoluzione Problemi

🆕 Problemi Risolti nelle Versioni Recenti

v1.0.6 - Documentazione Completa

• ✅ Documentazione aggiornata con tutte le soluzioni agli errori comuni
• ✅ Istruzioni step-by-step per ogni tipo di problema
• ✅ Esempi pratici per configurazione e troubleshooting

v1.0.5 - Dipendenze Automatiche

• ✅ ModuleNotFoundError risolto: Le dipendenze Python (google-auth-oauthlib, google-ads, ecc.) vengono installate automaticamente
• ✅ Script postinstall: Esegue automaticamente pip install -r requirements.txt
• ✅ Zero configurazione manuale: Non serve più installare manualmente le dipendenze Python

Errori Comuni Risolti

| Errore | Versione Risolta | Soluzione Implementata | |--------|------------------|------------------------| | ModuleNotFoundError: No module named 'google_auth_oauthlib' | v1.0.5 | Script postinstall automatico | | ModuleNotFoundError: No module named 'google.ads' | v1.0.5 | Installazione automatica dipendenze | | Configurazione complessa | v1.0.6 | Documentazione semplificata | | Setup manuale dipendenze | v1.0.5 | Automazione completa |

Problemi Autenticazione

| Problema | Sintomi | Soluzione | |----------|---------|----------| | Nessun token trovato | Messaggio "Avvio flusso OAuth" | ✅ Normale per primo setup - completa autenticazione browser | | Refresh token fallito | Errore "Refresh token fallito" | ✅ Elimina google_ads_token.json e ri-autentica | | Flusso OAuth fallito | Errore browser o nessuna risposta | Controlla percorso file credenziali e connessione internet | | Permesso negato | "Accesso negato" nel browser | Assicurati che l'account Google abbia accesso Google Ads |

Problemi Configurazione

| Problema | Sintomi | Soluzione | |----------|---------|----------| | Variabili ambiente mancanti | "Variabile ambiente non impostata" | Controlla file .env e sezione env config Trae.ai | | File non trovato | "FileNotFoundError" | Verifica percorsi assoluti nella configurazione | | Errori import moduli | "ModuleNotFoundError" | Esegui pip install -r requirements.txt | | Problemi percorso Python | "Comando non trovato" | Usa percorso assoluto all'eseguibile Python |

Problemi API

| Problema | Sintomi | Soluzione | |----------|---------|----------| | ID cliente non valido | "Cliente non trovato" | Usa formato 10 cifre senza trattini: 1234567890 | | Quota API superata | Errore "Quota superata" | Attendi reset quota o richiedi aumento | | Developer token non valido | "Autenticazione fallita" | Verifica token nel Centro API Google Ads | | Errori sintassi GAQL | "Query non valida" | Controlla sintassi GAQL e nomi campi |

Modalità Debug

Abilita logging dettagliato per risoluzione problemi:

# Aggiungi a server.py per debug
import logging
logging.basicConfig(level=logging.DEBUG)

🚀 Configurazione Avanzata

Modalità Trasporto HTTP

Per deployment web o accesso remoto:

# Avvia server in modalità HTTP
python3 server.py --http

Config Trae.ai per HTTP:

{
  "google-ads": {
    "url": "http://127.0.0.1:8000/mcp"
  }
}

Storage Token Personalizzato

Modifica posizione storage token in oauth/google_auth.py:

# Posizione file token personalizzata
def get_token_path():
    return "/percorso/sicuro/personalizzato/google_ads_token.json"

Configurazione Account Manager

Per gestire più account sotto un MCC:

# Aggiungi al file .env
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890

📊 Limiti e Quote API

Quote Google Ads API

• Accesso base: 15.000 operazioni al giorno
• Accesso standard: 40.000 operazioni al giorno
• Tasso richieste: 1.600 richieste al minuto per developer token

Best Practice per Uso API

1. Cache risultati quando possibile per ridurre chiamate API
2. Usa intervalli date per limitare volume dati
3. Richieste batch quando supportate
4. Monitora uso nella Google Cloud Console
5. Implementa logica retry per errori limite tasso

📄 Licenza

Questo progetto è sotto licenza MIT - vedi il file LICENSE per dettagli.

Realizzato con ❤️ per la community MCP e Trae.ai

Connetti i tuoi dati Google Ads direttamente agli assistenti AI e sblocca potenti insights pubblicitari attraverso conversazioni in linguaggio naturale.