Collegare Search Console a Claude Code

Google Analytics ti dice chi è arrivato sul tuo sito. Search Console ti dice chi ci ha provato: quali parole ha scritto su Google, quante volte sei comparso, in che posizione e quante volte qualcuno ha cliccato. Sono le due metà della stessa domanda, e la seconda è quella che si guarda più di rado, perché la dashboard è più lenta da attraversare e i confronti fra periodi vanno ricostruiti a mano ogni volta.

Con un collegamento MCP l’agente da terminale interroga Search Console al posto tuo. Tu scrivi “com’è andata questa settimana rispetto alla precedente”, lui prende le query, le impressioni e le posizioni, le confronta e ti lascia un file sul disco.

In questa ricetta colleghiamo una proprietà Search Console a Claude Code. Se hai già fatto la ricetta su Google Analytics, metà del lavoro è già in piedi e qui ti resta poco: stesso progetto Cloud, stesso account di servizio, stessa chiave. Ma c’è una differenza che cambia il tono di tutto l’articolo, e conviene dirla subito.

Qui il server ufficiale non c’è

Per Analytics, Google pubblica un server MCP suo. Per Google Ads anche. Per Search Console no. Alla data di questo articolo non esiste un server MCP ufficiale di Google per Search Console: non compare nell’elenco dei server gestiti da Google, né nella documentazione dell’API. Esistono solo server scritti dalla comunità, oppure scritti da te.

Non è un dettaglio da nota a piè di pagina, perché cambia chi risponde di quel pezzo di macchina. Con un server ufficiale, quando Google modifica qualcosa è Google ad aggiornarlo. Con un server di terzi, quel lavoro non lo fa nessuno finché non lo fai tu o non lo fa chi l’ha pubblicato, e non hai modo di sapere in anticipo quale delle due cose succederà.

Le tre strade possibili, in ordine di fatica crescente:

1. un server pubblicato da altri, preso da GitHub e compilato in casa. È la via più rapida. Il costo è che stai facendo girare sul tuo computer, con in mano una chiave dei tuoi dati Google, del codice scritto da uno sconosciuto;
2. lo stesso, ma dopo averlo letto. Un server MCP per Search Console è un programma di poche centinaia di righe che chiama un’API e restituisce il risultato. Non serve saper programmare per farsi dire dall’agente cosa fa, quali indirizzi contatta e quali permessi chiede;
3. scrivertelo. Sembra il passo da esperti ed è invece la strada che alcuni trovano più semplice, perché decidi tu quali strumenti espone e con quale nome. È il tema del capitolo 7, che parla proprio del momento in cui l’attrezzo giusto non esiste e te lo costruisci.

Questa guida vale identica per tutte e tre: cambia da dove arriva il programma, non il resto della procedura. Quello che non cambia mai è la chiave, che sta sul tuo computer e non viene consegnata a nessuno: il server la usa per parlare con Google, e i permessi veri li decidi dentro Search Console.

Ingredienti

• una proprietà Search Console già verificata, con qualche giorno di storia alle spalle;
• il progetto Google Cloud, l’account di servizio e la chiave JSON della ricetta su Analytics. Se non li hai, il passo 5 di quella guida è il posto da cui partire: qui do per fatto quel lavoro;
• Claude Code già installato e funzionante;
• Node.js, se il server che scegli è scritto in JavaScript, o Python se è in Python. Lo dice il progetto che installi;
• un quarto d’ora, se vieni dalla ricetta su Analytics. Se parti da zero, aggiungi la mezz’ora di Google Cloud di quella guida.

Chi fa cosa: tu e l’agente

Vale la stessa divisione della ricetta su Analytics, e per lo stesso motivo: non è una preferenza, è una barriera. L’agente vive nel terminale, non ha il tuo browser e non è dentro i tuoi account Google.

Quello che devi fare tu. Attivare l’API dentro Google Cloud e autorizzare l’account di servizio dentro Search Console. Sono due schermate e cinque minuti, e sono i passi 1 e 2.

Quello che può fare l’agente. Procurarsi il server, compilarlo, metterlo al posto giusto, scrivere la configurazione, verificare che risponda e fare la prima interrogazione. Sono i passi 3, 4 e 5.

Se scegli di delegare, la richiesta da incollare è questa:

Leggi la guida che trovi a questo indirizzo e collegami Search Console a questa
cartella: [incolla qui l'indirizzo di questa pagina]

Dati che ho già: la proprietà è https://ilmiosito.it/, e la chiave del service
account è il file ~/.credentials/google-marketing.json, già scaricata.

Prima di toccare qualsiasi cosa, elencami i passaggi che devo fare io a mano
nelle schermate di Google, perché tu non puoi farli.

Il server MCP per Search Console non è ufficiale: prima di installarlo, dimmi
da quale repository lo prendi, quando è stato aggiornato l'ultima volta, quali
permessi chiede e quali indirizzi contatta. Voglio decidere io se installarlo.

Poi fai la tua parte, spiegandomi ogni comando prima di eseguirlo, e fermati
quando è il momento di verificare insieme che il collegamento funzioni.

Il paragrafo centrale è quello che questa ricetta aggiunge rispetto all’altra. Chiedere provenienza, data dell’ultimo aggiornamento e permessi richiesti prima di installare è la stessa domanda che faresti a un collaboratore che ti propone di installare qualcosa sul computer dell’ufficio. Un agente risponde volentieri, e la risposta la valuti tu.

1. Attiva l’API di Search Console

Se vieni dalla ricetta su Analytics, questa schermata l’hai già vista. Apri console.cloud.google.com, scegli lo stesso progetto che avevi creato — quello con il nome che non nomina un sito solo — e vai su API e servizi → Libreria.

Cerca Google Search Console API e clicca Abilita. Quando la scheda mostra la spunta verde al posto del pulsante, è fatto.

Questa è l’unica cosa che va aggiunta lato Cloud. Progetto, account di servizio e chiave sono già in piedi e non si toccano: è il vantaggio di aver fatto quel giro con un po’ di ordine la prima volta.

2. Autorizza l’account di servizio dentro Search Console

Come per Analytics, il pezzo che si dimentica sempre: l’account di servizio esiste, ma non vede ancora niente. Averlo creato non gli dà accesso ai tuoi dati. L’accesso si concede dentro Search Console, proprietà per proprietà.

Prendi l’indirizzo dell’account di servizio, che è il valore di client_email dentro il file della chiave:

grep client_email ~/.credentials/google-marketing.json

Questo comando lo può eseguire l’agente, ma vale la pena sapere che aspetto ha: è lo stesso indirizzo che finisce per iam.gserviceaccount.com e che rivedrai in ogni schermata dei permessi Google da qui in avanti.

Poi vai su search.google.com/search-console, scegli la proprietà e apri Impostazioni → Utenti e autorizzazioni. Clicca Aggiungi utente, incolla l’indirizzo e scegli l’autorizzazione Limitata.

Limitata è il livello più basso: vede i dati e non può gestire le impostazioni né gli utenti della proprietà. È quello che ti serve, ed è la scelta da fare anche se sei tentato di dare Completa “per sicurezza, così funziona”. Il ragionamento giusto è il contrario: parti dal minimo e alzi solo se qualcosa non risponde.

Le due parole per la stessa cosa

Una cosa che confonde e che vale la pena vedere una volta sola. L’interfaccia di Search Console e l’API chiamano gli stessi permessi con nomi diversi:

Quando fra due passi chiederai all’agente l’elenco dei siti, ti risponderà con la colonna di destra. Non è un altro permesso: è la stessa riga vista da un programma invece che da una pagina web. Sapendolo, la verifica del passo 5 diventa leggibile a colpo d’occhio.

3. Metti il server dove resterà

Un server MCP che ti compili in casa diventa una cartella sul tuo disco, e quella cartella deve stare in un posto stabile: se la sposti, ogni configurazione che la nominava smette di funzionare.

La convenzione che usiamo qui è una cartella MCP nella cartella utente, una sottocartella per servizio:

~/MCP/
├── mcp-gsc/            Search Console
├── mcp-google-ads/     Google Ads
└── mcp-email/          posta

Non è un progetto e non va su GitHub: è attrezzatura della macchina. Il motivo per cui conviene un posto solo è che lo stesso server serve a tutti i siti che segui, e un ls ~/MCP ti dice quali servizi esterni possono essere raggiunti dagli agenti su questo computer. È la domanda che ti farai fra sei mesi.

L’installazione dipende dal progetto che hai scelto, e le istruzioni stanno nel suo README: quasi sempre è scaricare, installare le dipendenze e compilare. È lavoro da agente, ed è il momento in cui il paragrafo sulla provenienza della richiesta di prima si ripaga.

4. Dichiara il server

Apri il terminale nella cartella del marketing — quella separata dal sito, come nella ricetta su Analytics — e registra il collegamento:

claude mcp add gsc \
  --scope project \
  -e "GOOGLE_APPLICATION_CREDENTIALS=/Users/tuonome/.credentials/google-marketing.json" \
  -- node /Users/tuonome/MCP/mcp-gsc/dist/index.js

Il comando scrive un file .mcp.json nella cartella. Vale la pena vedere che aspetto ha, perché è lo stesso in tutti i progetti e prima o poi ti capiterà di leggerlo per capire un errore:

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/Users/tuonome/MCP/mcp-gsc/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/tuonome/.credentials/google-marketing.json"
      }
    }
  }
}

Dentro c’è il percorso della chiave, non la chiave. Questo file può stare su GitHub: chi lo legge sa che esiste un collegamento a Search Console, non può usarlo. I percorsi vanno scritti assoluti, con /Users/tuonome/ davanti: la scorciatoia ~ qui non viene espansa.

Se segui più siti e ti ritrovi a copiare questa riga in cinque cartelle, la alternativa è --scope user, che rende il collegamento disponibile ovunque. Comodo, ma valutalo: con lo scope utente ogni sessione, in qualunque cartella, può interrogare tutte le proprietà autorizzate a quell’account di servizio. Se fra quelle ci sono siti di clienti, la comodità ha un costo che è meglio scegliere consapevolmente.

5. Verifica, e verifica la cosa giusta

Avvia l’agente nella cartella e scrivi:

/mcp

Deve comparire gsc con lo stato connected. Ma connesso non vuol dire autorizzato, e sono due guasti diversi con due rimedi diversi. La prova vera è la seconda:

Elenca le proprietà Search Console a cui hai accesso, con il livello di
permesso di ciascuna.

Se il tuo sito compare con siteRestrictedUser, i due pezzi combaciano: il server parla con Google, Google riconosce l’account di servizio, e il permesso è quello basso che volevi. È la tabella del passo 2, letta dall’altra parte.

La verifica che vale più di tutte

C’è una terza prova che quasi nessuno fa, ed è quella che ti dice se il permesso è davvero limitato a quello che credi. Chiedi all’agente di interrogare una proprietà che non hai autorizzato. Per esempio, se hai dato accesso a https://ilmiosito.it/, prova a chiedere i dati della proprietà a livello di dominio, sc-domain:ilmiosito.it, che in Search Console è una proprietà diversa.

La risposta deve essere un errore di permessi: User does not have sufficient permission for site. Sembra un fallimento ed è invece la cosa migliore che potesse succedere, perché ti dimostra con i tuoi occhi che il confine c’è e tiene. Un permesso che non hai mai visto negare qualcosa è un permesso di cui non sai niente.

6. La prima interrogazione, e cosa aspettarsi davvero

Adesso puoi chiedere a parole tue:

Quali sono le dieci query che hanno portato più clic negli ultimi 28 giorni?
Dammi clic, impressioni, CTR e posizione media.

Prima di guardare il risultato, però, due cose che spiegano quasi tutti gli sconcerti della prima volta.

I dati arrivano in ritardo. Search Console non è in tempo reale: gli ultimi due o tre giorni sono incompleti o assenti. Se chiedi “gli ultimi sette giorni” intendendo fino a oggi, stai chiedendo anche a giorni che non esistono ancora. La regola pratica è far finire l’intervallo tre giorni fa.

Se il sito è nuovo, non esce niente. E qui va detta una cosa che le guide saltano quasi sempre, perché fa una brutta figura: su un sito appena messo online, questa interrogazione risponde con una tabella vuota. Zero righe. Non è il collegamento che non funziona, non è la chiave sbagliata, non è un permesso mancante: è che Google non ha ancora abbastanza dati sul tuo sito da mostrarti.

È esattamente il tipo di errore che il capitolo 6 chiama l’errore che non si vede: tutto risponde correttamente, nessun messaggio rosso compare, e il risultato è vuoto per un motivo che sta fuori dalla macchina. La tentazione è rifare la configurazione da capo. La cosa giusta da fare è distinguere il guasto dal silenzio, e per farlo basta una domanda:

Elenca le proprietà a cui hai accesso, e per ognuna dimmi quante impressioni
totali risultano negli ultimi 90 giorni.

Se le altre proprietà rispondono con dei numeri e la tua con zero, il collegamento è a posto ed è il sito a essere giovane. Se rispondono zero tutte, allora sì, c’è qualcosa da controllare.

7. Il lavoro vero: il confronto fra due periodi

Con Analytics chiedi un numero. Con Search Console il numero da solo non dice quasi niente: cento impressioni sono tante o poche a seconda di quante ne avevi la settimana prima. Il lavoro vero è il confronto, ed è anche la parte che nella dashboard costa più fatica, perché i due periodi vanno impostati a mano ogni volta.

È il caso perfetto per una richiesta salvata su file, come la cartella domande/ della ricetta su Analytics. Per esempio domande/settimana-su-settimana.md:

Confronta l'ultima settimana con la precedente per la proprietà
https://ilmiosito.it/.

Le date calcolale così, e scrivile nel report:
- la fine dell'ultimo periodo è oggi meno tre giorni, perché i dati di Search
  Console arrivano in ritardo;
- ogni periodo dura sette giorni;
- il periodo precedente finisce il giorno prima dell'inizio di quello nuovo.

Voglio, in questo ordine:
1. clic, impressioni, CTR e posizione media dei due periodi affiancati, con la
   differenza in valore assoluto e in percentuale;
2. le query cresciute di più e quelle calate di più, con i numeri assoluti;
3. le query nuove, che nel periodo precedente non c'erano;
4. le pagine che hanno perso più clic;
5. tre cose che noti e che meritano un controllo, una riga ciascuna.

Regole per i numeri:
- scrivi sempre i valori assoluti accanto alle percentuali;
- dopo l'elenco delle query, dimmi quanti clic del totale non compaiono in
  nessuna riga, perché Search Console non mostra le ricerche rare;
- se una query passa da 1 a 4 clic, non scrivere "+300%" senza dire da quanto a
  quanto;
- se un numero ti sembra sbagliato, scrivi che sembra sbagliato invece di
  sistemarlo.

Salva il risultato in report/settimanali/AAAA-MM-GG.md e chiudi scrivendo le
date esatte dei due periodi interrogati e la data di oggi.

La settimana dopo apri l’agente e scrivi esegui domande/settimana-su-settimana.md. La domanda l’hai formulata una volta.

Tre righe di quella richiesta meritano di essere lette con attenzione, perché sono la competenza che resta anche quando cambi strumento.

Le date calcolate e scritte nel report. Un report che non dice quale periodo ha interrogato è un testo con dei numeri. Fra sei mesi non saprai se quei 340 clic erano sette giorni o trenta.

I valori assoluti accanto alle percentuali. Con numeri piccoli le percentuali mentono, e mentono in modo entusiasmante: +300% su un sito nuovo di solito vuol dire da uno a quattro. È la riga che più di ogni altra decide se il report ti sarà utile o se ti farà prendere decisioni su niente.

Segnalare l’anomalia invece di smussarla. Un agente che riceve un numero strano ha una tendenza naturale a raccontartelo in modo plausibile. Chiederglielo esplicitamente cambia il tipo di risposta che ricevi.

8. Che aspetto ha un confronto vero

I numeri che seguono sono veri, presi con questo collegamento su un sito con qualche anno di storia alle spalle. È il sito di un cliente, quindi le query sono descritte invece che riportate: i numeri sono quelli usciti dall’interrogazione, il testo delle ricerche no.

Prima i totali delle due settimane, che è la tabella con cui si apre il report:

Sembra una settimana buona, e in un certo senso lo è. Ma guarda cosa succede appena provi a raccontarla come la racconterebbe una dashboard: i clic sono cresciuti del 30%. È vero, ed è anche inutile. Trenta per cento vuol dire dieci clic. Bastano due persone che cercano il nome dell’azienda per fare quella percentuale, e la settimana prossima gli stessi dieci clic in meno diventeranno un -23% allarmante senza che sia successo niente.

È il motivo della regola nella richiesta del passo precedente. Con numeri di questa taglia, la percentuale da sola non è un’informazione: è un modo di far sembrare grande una cosa piccola.

Quello che i totali nascondono

Adesso la parte che rende utile il collegamento, e che dalla tabella qui sopra non si vede. Chiedendo la stessa settimana divisa per ricerca, le query che hanno portato almeno un clic sono sei, e si dividono così:

• 19 clic da persone che cercavano il nome del sito, in quattro grafie diverse: il nome giusto, il nome attaccato, il nome al plurale, il nome con una lettera in più. Tutte in prima o seconda posizione;
• 2 clic da ricerche su due argomenti specifici di cui il sito parla, una formazione rocciosa e un fenomeno vulcanico.

Ed è qui che conviene fermarsi a fare una somma, perché è la cosa che nessuno avverte: 19 più 2 fa 21, ma i clic della settimana erano 43. Metà mancano all’appello, e non è un errore del collegamento.

Search Console non mostra le ricerche fatte da pochissime persone, per non rendere identificabile chi le ha fatte. Quei clic finiscono nel totale ma non compaiono in nessuna riga. È una cosa da sapere prima di costruirci sopra un ragionamento: la somma delle query non fa mai il totale della proprietà, e se ti aspetti che lo faccia passerai un pomeriggio a cercare un guasto che non c’è. Vale la pena farlo scrivere nel report, chiedendo all’agente di indicare quanti clic restano fuori dalle righe mostrate.

Detto questo, la metà che si vede parla chiaro: diciannove clic su ventuno vengono da chi il sito lo stava già cercando. Non è una brutta notizia, ma cambia cosa vuol dire quel +30%. Fra le ricerche visibili, il lavoro sui contenuti — quello che dovrebbe portare persone che non ti conoscono — in questa settimana ha prodotto due clic.

Questo è il tipo di frase che un’esportazione non ti dà e che una dashboard non ti mette davanti. Va chiesta, ed è esattamente quello che fa il punto 5 della richiesta salvata: tre cose che noti e che meritano un controllo.

Il segnale più interessante è dove i clic non ci sono

Nella stessa settimana c’è un gruppo di ricerche, tutte varianti sullo stesso argomento storico e tutte in inglese, che produce oltre venti impressioni e zero clic, con posizioni fra l’ottava e la decima.

Zero clic sembra la riga da ignorare. È invece la più ricca di tutte, perché dice tre cose insieme: che per quell’argomento Google ti mostra, che ti mostra abbastanza in basso perché nessuno arrivi fin lì, e che le persone che cercano quella cosa parlano un’altra lingua. Sono tre decisioni possibili — migliorare quella pagina, scriverne una in inglese, oppure lasciar perdere perché quel pubblico non compra — e nessuna delle tre ti verrebbe in mente guardando il totale dei clic.

È questa la ragione per cui vale la pena collegare Search Console a un agente. Non per avere i numeri più in fretta: per avere qualcuno che li attraversa tutti ogni settimana, comprese le righe con zero, che sono quelle che nella dashboard scorri senza vedere.

E la posizione media?

Un’ultima avvertenza su quel 12,5, perché è il numero più frainteso di Search Console. Non è la posizione del tuo sito su Google: è la media delle posizioni in cui sei comparso per ricerche diversissime fra loro. Nell’esempio, la media mette insieme la prima posizione sul nome dell’azienda e la trentaduesima su una ricerca generica. Migliora di 1,6 punti perché è cambiato il mix delle ricerche, non necessariamente perché il sito si sia mosso.

Con Search Console la posizione si guarda query per query, mai in totale. Se vuoi che il report sia onesto, chiedigli la posizione delle singole ricerche che ti interessano, non la media della proprietà.

Se lavori su siti che non sono tuoi

Va detto qui e non in fondo, perché riguarda la maggior parte di chi legge una guida come questa.

Se le proprietà che colleghi sono di clienti, quello che passa nella conversazione con l’agente non sono numeri anonimi: sono le query per cui quel sito compare su Google, cioè informazione commerciale di qualcun altro. Due conseguenze pratiche.

Il perimetro va deciso prima. È il motivo per cui --scope project è la scelta prudente: apri l’agente nella cartella di quel cliente e vedi quel cliente. Con lo scope utente ogni sessione può interrogare tutto.

La condivisione va concordata. Che i dati di un cliente transitino da un servizio di IA è una cosa da dire a quel cliente, non da dare per scontata. Il capitolo 8 è dedicato interamente a questo, cioè a cosa cambia quando il materiale su cui lavori non è tuo.

Cosa questo collegamento non fa

Non migliora il posizionamento. Ti dice cosa sta succedendo. Cosa farne resta lavoro tuo, e nessuna delle due cose la fa l’agente al posto tuo.

Non modifica niente. Con l’autorizzazione Limitata l’agente legge e basta. Su questo però una precisazione onesta: alcuni server MCP per Search Console chiedono a Google anche il permesso di scrittura, per comodità di chi li ha scritti. Se il server che installi lo fa, il tuo argine vero resta l’autorizzazione Limitata dentro Search Console, che non concede quelle azioni a prescindere da cosa chiede il programma. Vale comunque la pena guardare quali permessi chiede: se puoi scegliere una versione che chiede solo lettura, scegli quella.

Non vede Analytics. Sono servizi diversi con collegamenti diversi. Se vuoi entrambi, sono due server dichiarati nello stesso file, e l’agente li usa insieme senza che tu debba fare niente di speciale.

Non sostituisce l’interfaccia. Alcune cose in Search Console si guardano meglio a schermo, e l’ispezione di un singolo URL è una di quelle.

Domande frequenti

/mcp dice failed. Cosa guardo?

Nell’ordine, perché sono le cause quasi sempre:

1. il percorso nel comando è sbagliato. Sia quello del programma sia quello della chiave devono essere assoluti, senza ~;
2. il server non è stato compilato. Se il progetto va costruito e quel passo è saltato, il file che stai lanciando non esiste;
3. l’API non è attiva nel progetto Google Cloud. Torna al passo 1.

Si collega ma dice che non ha il permesso sul sito

È l’autorizzazione dentro Search Console, non la configurazione. O l’account di servizio non è stato aggiunto, oppure è stato aggiunto da pochi minuti e il permesso non si è propagato. Controlla anche di stare chiedendo la proprietà giusta: https://ilmiosito.it/ e sc-domain:ilmiosito.it sono due proprietà distinte, e il permesso su una non vale sull’altra.

Perché la somma delle query non fa il totale?

Perché Search Console non mostra le ricerche fatte da pochissime persone, per non renderle identificabili. Quei clic restano contati nel totale della proprietà ma non compaiono in nessuna riga. Su un sito piccolo la parte non attribuita può essere metà del traffico: nell’esempio di questa guida erano 21 clic su 43. Non è un guasto e non si può recuperare.

Perché i numeri non coincidono con quelli di Analytics?

Perché misurano cose diverse, non perché uno dei due sbagli. Search Console conta quello che succede nei risultati di Google prima del clic; Analytics conta quello che succede sul sito dopo. Aspettarsi che i totali combacino porta a cercare un guasto che non c’è.

Funziona anche con Codex?

Sì. Il server e le credenziali sono gli stessi: cambia il file dove si dichiara il collegamento, che in Codex è ~/.codex/config.toml invece di .mcp.json.

Devo rifare Google Cloud per ogni sito?

No. Progetto, account di servizio e chiave sono infrastruttura della macchina. Per una proprietà nuova resta solo il passo 2: aggiungere l’account di servizio come utente Limitata.

Da dove continuare

Se il collegamento ad Analytics non l’hai ancora fatto, è il gemello di questa ricetta e conviene farli in fila: Collegare Google Analytics a Claude Code.

Se l’idea di far girare un programma non ufficiale sul tuo computer ti ha messo a disagio — ed è un disagio sano — il capitolo 7 racconta il momento in cui l’attrezzo che ti serve non esiste e te lo costruisci.

Puoi anche iscriverti agli aggiornamenti per ricevere le prossime ricette.

Fonti ufficiali

• Search Console API
• Search Analytics: query e limiti
• Permessi e livelli di accesso in Search Console
• Account di servizio in Google Cloud
• MCP in Claude Code
• Model Context Protocol