Errori di configurazione del Search Console MCP

Soluzioni agli errori dei server MCP Search Console della community: API non attiva, 403, sc-domain, accesso bloccato, invalid_grant, spawn uvx ENOENT.

Di Denis Veisllari

La maggior parte degli errori di un Google Search Console MCP nasce in cinque punti: il progetto Google Cloud, la proprietà Search Console, la schermata di consenso OAuth, il file delle credenziali e la configurazione del client AI. Trova il tuo messaggio di errore qui sotto, correggi quel passaggio e riavvia il client. Se preferisci evitare del tutto Google Cloud, l'ultima sezione mostra la strada che richiede solo un accesso Google.

Google non ha pubblicato un server MCP ufficiale per Search Console. Il suo repository MCP copre Google Analytics, BigQuery, Maps e altri prodotti, ma non Search Console, quindi ogni server Search Console che puoi installare è un progetto della community. I due più usati sono mcp-gsc (installato come mcp-search-console) e mcp-server-gsc. Gli errori qui sotto valgono per entrambi e per quasi tutti gli altri.

Consultazione rapida

Cosa vediCausa probabileVai a
"has not been used in project ... before or it is disabled"La Search Console API è disattivata in quel progetto CloudAPI non attiva
403 "User does not have sufficient permission for site"Account di servizio non aggiunto alla proprietà, o URL sbagliatoErrori di autorizzazione
"is not a verified Search Console site in this account"Confusione tra proprietà di dominio e prefisso URLFormato della proprietà sbagliato
"Failed to add user: email not found" in Search ConsoleBug di Google con i nuovi account di servizioEmail non trovata
"Access blocked" o "Error 403: access_denied" nella schermata GoogleApp OAuth in modalità Test, e non sei un utente di testErrori della schermata OAuth
invalid_grant circa una settimana dopo che funzionavaIn modalità Test i refresh token scadono dopo 7 giorniFunziona, poi si ferma
"Error 400: redirect_uri_mismatch"Client Web usato dove serve un client DesktopErrori della schermata OAuth
"Service account credentials file not found"Percorso relativo, o pacchetto sbagliatoFile delle credenziali
spawn uvx ENOENT o spawn npx ENOENTIl client non trova il comandoErrori del client
Non compare nessuno strumento e non viene scritto alcun logPython precedente alla 3.11Errori del client
I numeri non coincidono con la dashboard di Search ConsoleRitardo dei dati, limiti di righe, query anonimizzateNumeri diversi

L'API non è attiva

L'errore è un 403 che dice che la Google Search Console API "has not been used in project" (non è mai stata usata nel progetto), seguito da un numero di progetto, spesso con un link per attivarla.

L'API va attivata nello stesso progetto Cloud a cui appartengono il tuo client OAuth o il tuo account di servizio. L'errore tipico è attivarla in un altro progetto.

  1. Confronta il numero di progetto nell'errore con il progetto del tuo file JSON delle credenziali.
  2. In Google Cloud, apri APIs & Services > Library in quel progetto e attiva Google Search Console API.
  3. Aspetta qualche minuto e riprova. Google avverte che le nuove impostazioni possono impiegare un po' a propagarsi nei suoi sistemi.

Errori di autorizzazione

L'errore è un 403 "User does not have sufficient permission for site". Il controllo URL mostra invece "The caller does not have permission".

Creare un account di servizio non gli dà alcun accesso a Search Console. La sua email va aggiunta esattamente alla proprietà che interroghi.

  1. Apri la chiave JSON dell'account di servizio e copia il valore di client_email.
  2. In Search Console, apri Impostazioni > Utenti e autorizzazioni > Aggiungi utente, incolla l'email e assegna l'autorizzazione Completa.
  3. Se invece accedi con OAuth, usa un account Google che vede già la proprietà in Search Console.

Se l'account ha accesso e ricevi ancora un 403, probabilmente la stringa della proprietà è sbagliata. Leggi la sezione successiva.

Il formato della proprietà è sbagliato

L'errore è "'sc-domain:example.com' is not a verified Search Console site in this account", oppure lo stesso 403 visto sopra.

Search Console ha due tipi di proprietà, e l'API vuole la stringa esatta di quella che hai:

  • Proprietà di dominio: sc-domain:example.com
  • Proprietà con prefisso URL: l'URL completo con protocollo e barra finale, per esempio https://www.example.com/

http e https sono proprietà diverse, così come www e il dominio senza www. Non tirare a indovinare. Chiedi all'agente di eseguire lo strumento del server che elenca i siti e copia l'URL del sito esattamente come viene restituito.

Search Console dice che l'email dell'account di servizio non esiste

Quando aggiungi l'account di servizio come utente, Search Console risponde "Failed to add user: email not found".

È un problema di Google con gli account di servizio appena creati, non un tuo errore. È stato segnalato per la prima volta verso aprile 2026, si è ripresentato a settembre 2026 e riguarda anche Google Analytics. Google lo ha riconosciuto ma non ha indicato una data per la correzione. Gli utenti segnalano tre soluzioni alternative:

  • Aspettare da qualche ora a un giorno e aggiungere di nuovo l'utente.
  • Aggiungere l'utente tramite l'API invece che dalla schermata di Search Console.
  • Usare OAuth invece di un account di servizio, se il tuo server lo supporta.

Errori della schermata OAuth

"Access blocked" con "Error 403: access_denied". La tua schermata di consenso è in modalità Test e l'account Google con cui hai fatto l'accesso non è un utente di test. In Google Cloud, apri Google Auth Platform > Audience > Test users e aggiungi il tuo indirizzo.

"Google hasn't verified this app". Compare quando un'app non verificata chiede l'accesso a Search Console. Se hai creato tu il progetto Cloud e lo usi solo tu, puoi proseguire oltre l'avviso. La verifica conta solo se dai l'app ad altre persone.

"Error 400: redirect_uri_mismatch". Hai creato un client OAuth di tipo "Web application", ma i server locali accedono tramite un indirizzo di loopback come http://localhost con una porta casuale. Crea un nuovo client OAuth di tipo Desktop app, scarica il suo JSON e indicalo al server. Per mcp-gsc è l'impostazione GSC_OAUTH_CLIENT_SECRETS_FILE.

Funzionava, poi si è fermato dopo una settimana

L'errore è invalid_grant, di solito "Token has been expired or revoked".

Google fa scadere i refresh token dopo 7 giorni quando la schermata di consenso di un'app esterna è ancora in modalità Test. I token smettono di funzionare anche se revochi l'accesso o non li usi per sei mesi.

  1. In Google Cloud, imposta lo stato di pubblicazione della schermata di consenso su In production. Per uso personale può restare non verificata.
  2. Elimina il file del token salvato dal server.
  3. Accedi di nuovo.

Se usi mcp-gsc, aggiornalo anche. Le versioni precedenti alla 0.4.2 potevano non riuscire ad aggiornare i token in sola lettura ed eliminare il file del token.

Il file delle credenziali non viene trovato

L'errore è "Service account credentials file not found".

  • Percorso relativo. Strumenti come uvx avviano il server da una cartella di cache, quindi un percorso come ./key.json non porta da nessuna parte. Usa il percorso completo nella configurazione del client. Su Windows, raddoppia le barre rovesciate: C:\\Users\\you\\key.json.
  • Pacchetto sbagliato. Per mcp-gsc, installa mcp-search-console, non il pacchetto mcp-gsc su PyPI, che non c'entra. Avvialo con uvx mcp-search-console@latest per avere la versione attuale.
  • File sbagliato nell'impostazione sbagliata. Una chiave di account di servizio contiene "type": "service_account" e un client_email. Un file di client OAuth inizia con una chiave installed o web. Ognuno va nella sua impostazione; mcp-gsc usa GSC_CREDENTIALS_PATH per il primo e GSC_OAUTH_CLIENT_SECRETS_FILE per il secondo, e mcp-server-gsc usa GOOGLE_APPLICATION_CREDENTIALS.

Il client non riesce ad avviare il server

spawn uvx ENOENT o spawn npx ENOENT. Le app desktop non caricano il PATH del tuo terminale, quindi non trovano il comando. Metti il percorso completo in "command". Lo ottieni con which uvx su macOS o Linux, o con where uvx su Windows. Per npx su Windows, usa "command": "cmd" con gli argomenti ["/c", "npx", "-y", ...].

Nessuno strumento, nessun file di log. mcp-gsc richiede Python 3.11 o successivo e sulle versioni precedenti fallisce senza dire nulla. Avvialo tramite uvx, che sceglie per te un Python adatto, oppure installa Python 3.12.

Le modifiche alla configurazione non hanno effetto. Controlla che nel JSON non ci siano virgole finali o barre rovesciate non raddoppiate, poi chiudi del tutto l'app e riaprila. Su Mac chiudere la finestra non basta; usa Cmd+Q.

Dove si trovano i log:

  • Claude Desktop su macOS: ~/Library/Logs/Claude. mcp.log contiene gli errori di connessione, e mcp-server-<name>.log gli errori di quel server.
  • Claude Desktop su Windows: %APPDATA%\Claude\logs.
  • Claude Code: esegui claude mcp get <name> per vedere l'errore, oppure /mcp in una sessione.
  • Cursor: apri il pannello Output e scegli MCP Logs.

Un ultimo limite: i server locali girano solo nelle app desktop e da terminale. Non funzionano su claude.ai nel browser né in ChatGPT, che richiedono un server remoto.

I numeri non coincidono con la dashboard

Non sono errori, ma sono all'origine della maggior parte delle segnalazioni del tipo "l'agente ha sbagliato".

  • Ritardo. I dati di Search Console arrivano di solito dopo due o tre giorni, e i giorni più recenti possono ancora cambiare. Alcuni server chiedono solo dati definitivi, quindi gli ultimi giorni risultano vuoti.
  • Limiti di righe. Una richiesta API restituisce al massimo 25.000 righe, e Google espone al massimo 50.000 righe al giorno per tipo di ricerca. Le query a coda lunga di un sito grande vengono tagliate.
  • Query mancanti. Le query rare e personali vengono escluse, quindi le righe delle query non arrivano mai al totale dei clic. Per totali esatti, chiedi dati senza la dimensione query o pagina.
  • Totali diversi. Il grafico somma per proprietà e la tabella per pagina, quindi i due possono differire. Controlla anche l'intervallo di date; i dati orari usano l'ora del Pacifico.
  • Quote. Il controllo URL consente 2.000 verifiche al giorno per sito, quindi i controlli in blocco su un sito grande si fermano a metà. Search Analytics consente 1.200 query al minuto per sito.

Evitare del tutto Google Cloud

Tutti gli errori qui sopra, tranne l'ultima sezione, nascono dal gestire un tuo progetto Google Cloud. Il Google Search Console MCP di zaDojo è ospitato per te: colleghi Search Console in un progetto zaDojo con un normale accesso Google, e il tuo agente lo legge all'indirizzo https://app.zadojo.com/mcp. Niente progetto Cloud, API da attivare, account di servizio, schermata di consenso o file di credenziali, e funziona in claude.ai e ChatGPT oltre che nei client desktop.

Le letture di Search Console, il controllo URL e la copertura dell'indice sono gratuiti con il piano Free di zaDojo, che non richiede carta. Lo stesso vale per le letture di Google Analytics e per gli audit del sito fino a 50 pagine. I dati su keyword, concorrenti e visibilità AI consumano crediti. Per confrontarlo con le altre opzioni gratuite, vedi server MCP SEO gratuiti.

Domande frequenti

Esiste un server MCP ufficiale di Google Search Console? No. Google pubblica server MCP per Google Analytics e altri prodotti, ma non per Search Console. Ogni server Search Console è un progetto della community o un servizio ospitato.

Meglio un account di servizio o OAuth? Un account di servizio è adatto a un server che gira senza supervisione, ma devi aggiungere la sua email a ogni proprietà. OAuth usa il tuo account Google e vede tutte le proprietà a cui hai già accesso, ma in modalità Test devi riaccedere ogni 7 giorni finché non lo imposti su In production.

Perché il mio agente vede solo alcuni dei miei siti? L'account o l'account di servizio che usa vede solo le proprietà a cui è stato aggiunto. Chiedi all'agente di elencare i siti e confronta l'elenco con Search Console.

Un server MCP Search Console può modificare il mio sito? No. Questi server leggono e gestiscono i dati di Search Console. Nessuno modifica le tue pagine.