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

$3

#### 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
`bash


Verifica che il pacchetto sia installato correttamente

npm list google-ads-mcp-server

Per installazione globale, verifica il comando

google-ads-mcp --help
`

$3

`bash


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

$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 --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:

`bash


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:
`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
``

📊 Limiti e Quote API

$3

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

$3

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.