Come collegare Yandex Direct a Gemini via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → Yandex Direct, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

Yandex Direct + Gemini

Fai analizzare alla tua AI la tua pubblicità su Yandex Direct, in sola lettura: campagne, gruppi di annunci, annunci, keyword e offerte, sitelink e callout, clienti di agenzia, dizionari, tracciamento delle modifiche e report statistici per giorno, campagna, annuncio o query di ricerca.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

YANDEX_DIRECT_TOKEN

Step 1 — Ottieni le credenziali

La configurazione richiede circa 10 minuti, più il tempo che Yandex impiega ad approvare l'accesso API (da un'ora a qualche giorno lavorativo). Ti servono un account Yandex Direct con almeno una campagna e una tua app registrata su oauth.yandex.ru.

1. Registra un'app su oauth.yandex.ru: piattaforma servizi web, con il permesso Yandex Direct API (direct:api). Annota il suo ClientID.
2. Nell'interfaccia web di Yandex Direct apri Tools → API, invia una richiesta di accesso API per quel ClientID e accetta il contratto d'uso dell'API. Finché Yandex non approva la richiesta, le chiamate falliscono con l'errore 58.
3. Con l'account Direct collegato, apri https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID> con il tuo ClientID e copia l'access_token (inizia con y0_) in YANDEX_DIRECT_TOKEN, senza Bearer o OAuth davanti. Il token vale circa un anno e si rinnova finché viene usato.
4. Solo per le agenzie: imposta YANDEX_DIRECT_CLIENT_LOGIN sul login Yandex dell'inserzionista da leggere; yandex_direct_list_agency_clients elenca questi login. Lascialo vuoto per il tuo account.
5. Installa il connettore ed esegui yandex_direct_get_client: mostra l'account, il suo login e la sua valuta.

Cosa legge: le campagne con tipo, stato, condizione, date, fondi e clic e impressioni totali, più la strategia di offerta; i gruppi di annunci con regioni e keyword negative; gli annunci con titolo, testo e link; keyword e autotargeting con offerte e produttività; le offerte delle keyword con le offerte e il traffico necessari per ogni posizione nella ricerca; sitelink, callout, set condivisi di keyword negative ed elenchi di retargeting; i clienti di agenzia; dizionari come valute e regioni; quali campagne sono cambiate da un certo momento; e i report statistici per giorno, campagna, annuncio o query di ricerca.

Report: yandex_direct_get_report restituisce testo separato da tabulazioni, con i nomi delle colonne nella prima riga e gli importi in decimali. I report piccoli arrivano subito. Quelli più grandi vengono preparati offline: l'AI richiede di nuovo con gli stessi parametri dopo l'attesa indicata da Yandex. In coda possono stare al massimo 5 report offline, e i report sulle query di ricerca sono solo offline e coprono gli ultimi 180 giorni.

Importi e pagine: offerte, budget e fondi arrivano come interi in micros (2500000 = 2,50 nella valuta dell'account). Gli elenchi restituiscono fino a 500 oggetti di default e al massimo 10.000, e gruppi, annunci e keyword si leggono per al massimo 10 campagne per chiamata.

Sola lettura per scelta: ogni tool legge. Nulla crea, modifica, mette in pausa o paga qualcosa, quindi non c'è niente da confermare e niente di disattivato all'installazione.

Limiti: ogni chiamata consuma punti API dalla quota giornaliera dell'inserzionista, e una chiamata fallita costa 20 punti. L'AI preferisce una chiamata con più id a tante chiamate singole e chiede solo i campi che le servono. L'errore 152 indica che i punti di oggi sono finiti; 506 che ci sono troppe richieste contemporanee.

Errori comuni: 53 significa che il token non è valido o è scaduto: prendine uno nuovo come al passo 3. 58 significa che l'accesso API dell'app non è ancora approvato. 54, 3000 o 3001 indicano nessun accesso API o nessun diritto, per esempio per un login cliente che il token non può leggere. 513 indica che il login non è collegato a Direct. 8000 e da 4000 a 4006 indicano un parametro sbagliato, 8800 un oggetto non trovato e 9300 troppi id in una chiamata.

Il connettore non crea né modifica campagne, annunci, keyword o offerte, non gestisce moderazione, budget o pagamenti e non usa la Sandbox né Wordstat.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Gemini

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Gemini CLI legge i server MCP da ~/.gemini/settings.json (su Windows %USERPROFILE%\.gemini\settings.json). Aggiungi:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia gemini.
3. Esegui /mcp in Gemini CLI (oppure gemini mcp list dal terminale): anythingmcp dovrebbe risultare connesso.
4. Inizia a scrivere prompt: Gemini CLI ora può chiamare i tool di Yandex Direct.

Tool disponibili

Esempi di prompt

• "Come sono andate le mie campagne la settimana scorsa? Mostrami impressioni, clic, CTR, costo e conversioni per campagna."
• "Quali query di ricerca hanno speso di più negli ultimi 30 giorni senza una sola conversione?"
• "Elenca le keyword della campagna Pneumatici invernali con le loro offerte, e dimmi cosa servirebbe per arrivare nelle prime posizioni."
• "Quali dei miei annunci sono stati rifiutati o non vengono mostrati in questo momento, e perché?"
• "Siamo un'agenzia: elenca i nostri clienti e mostrami la spesa di ieri del cliente romashka-shop."

FAQ

Dove cerca i server MCP Gemini CLI? In ~/.gemini/settings.json per il tuo utente, oppure in .gemini/settings.json dentro un progetto. gemini mcp list mostra ogni server e se si connette.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT