MCP Server per Google Ads API con autenticazione OAuth 2.0 automatica - Ottimizzato per Trae.ai
npm install 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 Globale
``bash`Installa globalmente per usare il comando 'google-ads-mcp' ovunque
npm install google-ads-mcp-server@1.0.6
#### Installazione Locale
`bash`Installa nel progetto corrente
npm install google-ads-mcp-server@1.0.6
> β
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
`bashVerifica che il pacchetto sia installato correttamente
npm list google-ads-mcp-server
$3
`bash
Clona il repository
git clone https://github.com/your-repo/google-ads-mcp-server.git
cd google-ads-mcp-serverInstalla le dipendenze Python
pip install -r requirements.txtEsegui 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
$3
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
$3
#### 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$3
#### 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
#### 3.1 Setup Automatico (Consigliato)
Dopo aver installato il pacchetto NPM, esegui il setup automatico:
`bash
Se installato globalmente
google-ads-mcp --setupSe installato localmente
npx google-ads-mcp-server --setupOppure 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:`bash
Richiesto: Google Ads API Developer Token
GOOGLE_ADS_DEVELOPER_TOKEN=il_tuo_developer_token_quiRichiesto: 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:
`json
{
"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:
`json
{
"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:
`json
{
"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
$3
1. Apri Trae.ai
2. Prova qualsiasi comando Google Ads, per esempio:
`
"Elenca tutti i miei account Google Ads"
`$3
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!
$3
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
$3
`
"Elenca tutti i miei account Google Ads""Mostra i dettagli dell'account e quali hanno campagne attive"
`$3
`
"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?"
`$3
`
"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"
`$3
`
"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
$3
- β
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$3
`bash
Imposta permessi sicuri per file sensibili
chmod 600 .env
chmod 600 google_ads_token.json
chmod 600 client_secret_*.json
`$3
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
$3
#### 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 |$3
| 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 |$3
| 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 |$3
| 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 |$3
Abilita logging dettagliato per risoluzione problemi:
`python
Aggiungi a server.py per debug
import logging
logging.basicConfig(level=logging.DEBUG)
`π Configurazione Avanzata
$3
Per deployment web o accesso remoto:
`bash
Avvia server in modalitΓ HTTP
python3 server.py --http
`Config Trae.ai per HTTP:
`json
{
"google-ads": {
"url": "http://127.0.0.1:8000/mcp"
}
}
`$3
Modifica posizione storage token in
oauth/google_auth.py:`python
Posizione file token personalizzata
def get_token_path():
return "/percorso/sicuro/personalizzato/google_ads_token.json"
`$3
Per gestire piΓΉ account sotto un MCC:
`bash
Aggiungi al file .env
GOOGLE_ADS_LOGIN_CUSTOMER_ID=123-456-7890
``- Accesso base: 15.000 operazioni al giorno
- Accesso standard: 40.000 operazioni al giorno
- Tasso richieste: 1.600 richieste al minuto per developer token
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
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.