Il server Model Context Protocol (MCP) di Google Analytics ti consente di collegare i tuoi dati di Google Analytics a modelli linguistici di grandi dimensioni (LLM) e agenti AI, come Gemini. Puoi utilizzare il server MCP per eseguire query sui report in linguaggio naturale, esaminare le configurazioni delle proprietà e creare agenti di analisi personalizzati.
Configura il server MCP Visualizza su GitHub Guarda il tutorial sulla configurazione
Prerequisiti
Prima di configurare il server MCP di Google Analytics, completa i seguenti requisiti:
- Installa Python e un gestore di pacchetti:
- Installa Python 3.10 o versioni successive.
- Installa
pipxouv(uvx) per eseguire il server MCP in un ambiente Python isolato.
Attiva le API di Google Analytics in :
- Crea o seleziona un progetto .
Attiva sia l'API Google Analytics Admin (
analyticsadmin.googleapis.com) sia l' API Google Analytics Data (analyticsdata.googleapis.com) nel tuo progetto:gcloud services enable analyticsadmin.googleapis.com \ analyticsdata.googleapis.com \ --project=YOUR_PROJECT_ID
Concedi l'accesso alla proprietà Google Analytics:
- Nell'interfaccia utente di Google Analytics, concedi al tuo account utente o di servizio almeno il ruolo Visualizzatore (
roles/analytics.viewer) nella proprietà Google Analytics di destinazione. Per istruzioni, consulta Gestisci le restrizioni relative a dati e accessi.
- Nell'interfaccia utente di Google Analytics, concedi al tuo account utente o di servizio almeno il ruolo Visualizzatore (
Configura l'autenticazione
Il server MCP di Google Analytics esegue l'autenticazione utilizzando le Credenziali predefinite dell'applicazione (ADC) con l'ambito OAuth 2.0 di Google Analytics di sola lettura:
https://www.googleapis.com/auth/analytics.readonly
Puoi configurare ADC utilizzando il tuo Account Google o un service account.
Opzione 1: autenticati con le credenziali utente
- Installa e inizializza gcloud CLI.
Esegui
gcloud auth application-default logincon gli ambiti richiesti:gcloud auth application-default login \ --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"Se utilizzi un file di configurazione del client web o desktop OAuth 2.0 scaricato (vedi Gestisci client OAuth), passa
--client-id-file:gcloud auth application-default login \ --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" \ --client-id-file=YOUR_CLIENT_JSON_FILEAl termine del comando, copia il percorso delle credenziali stampato nella console (
Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]). Utilizza questo percorso inGOOGLE_APPLICATION_CREDENTIALSdurante la configurazione del client MCP.
Opzione 2: autenticati con un service account
Per eseguire l'autenticazione con un service account che dispone dell'accesso in visualizzazione Visualizzatore alla tua proprietà Google Analytics:
- File della chiave JSON del service account:imposta
GOOGLE_APPLICATION_CREDENTIALSnella configurazione del client MCP sul percorso assoluto del file JSON del service account. Simulazione dell'identità dei service account: genera le credenziali ADC simulando l'identità del service account con gcloud CLI:
gcloud auth application-default login \ --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \ --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"
Configura il client MCP
Il server è pubblicato su PyPI come analytics-mcp ed espone gli script della console analytics-mcp e google-analytics-mcp.
Nelle seguenti configurazioni, sostituisci:
PATH_TO_CREDENTIALS_JSONcon il percorso assoluto del file JSON dell'ADC o del service account.YOUR_PROJECT_IDcon l'ID progetto in cui hai abilitato le API di Google Analytics.
Antigravity CLI e Antigravity IDE
- Installa Antigravity CLI o Antigravity IDE.
Aggiungi il server
analytics-mcpa~/.gemini/config/mcp_config.json(o.agents/mcp_config.jsonnel tuo workspace):{ "mcpServers": { "analytics-mcp": { "command": "pipx", "args": ["run", "analytics-mcp"], "env": { "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON", "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID" } } } }Verifica che
analytics-mcpsia connesso:- Antigravity CLI: esegui
agy, quindi inserisci/mcpper visualizzare i server MCP configurati. - Antigravity IDE:apri Impostazioni > Personalizzazioni > Server MCP installati e fai clic su Aggiorna.
- Antigravity CLI: esegui
Claude Desktop e Claude Code
Per Claude Desktop, aggiungi il server al file claude_desktop_config.json
(~/Library/Application Support/Claude/claude_desktop_config.json su macOS o
%APPDATA%\Claude\claude_desktop_config.json su Windows):
{
"mcpServers": {
"analytics-mcp": {
"command": "pipx",
"args": ["run", "analytics-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
"GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
}
}
}
}
Per Claude Code, registra il server utilizzando lo strumento a riga di comando:
claude mcp add analytics-mcp \
--scope user \
-e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" \
-e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \
-- pipx run analytics-mcp
Cursore
Aggiungi il server a .cursor/mcp.json nella directory del progetto (o ~/.cursor/mcp.json per la configurazione globale). Puoi richiamare google-analytics-mcp utilizzando uvx o pipx:
{
"mcpServers": {
"google-analytics-mcp": {
"command": "uvx",
"args": ["--from", "analytics-mcp", "google-analytics-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
"GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
}
}
}
}
Per eseguire l'ultima versione di sviluppo direttamente da GitHub utilizzando uvx, aggiorna "args":
"args": [
"--from",
"git+https://github.com/googleanalytics/google-analytics-mcp.git",
"google-analytics-mcp"
]
In alternativa, per utilizzare pipx, cambia "command" in "pipx" e imposta "args"
su:
"command": "pipx",
"args": [
"run",
"--spec",
"git+https://github.com/googleanalytics/google-analytics-mcp.git",
"google-analytics-mcp"
]
Strumenti MCP disponibili
Il server MCP di Google Analytics utilizza l'API Admin e l'API di dati v1 per esporre strumenti di sola lettura al tuo client MCP:
- Rilevamento di account e proprietà (API Admin):
get_account_summaries: elenca gli account e le proprietà Google Analytics accessibili all'utente autenticato (accountSummaries.list).get_property_details: restituisce i dettagli di configurazione di una proprietà Google Analytics specifica (properties.get).list_google_ads_links: elenca i link agli account Google Ads per una proprietà (properties.googleAdsLinks.list).list_property_annotations: elenca le annotazioni configurate per una proprietà (properties.reportingDataAnnotations.list).
- Reporting e ispezione dello schema (API di dati v1):
get_custom_dimensions_and_metrics: recupera le dimensioni e le metriche personalizzate definite per una proprietà (getMetadata).run_report: esegue un report standard di Google Analytics (runReport).run_realtime_report: esegue un report in tempo reale di Google Analytics (runRealtimeReport).run_funnel_report: esegue un report sull'esplorazione del funnel di Google Analytics (runFunnelReport).run_conversions_report: esegue un report sul rendimento delle conversioni (runConversionsReport).
Prompt di esempio
Una volta stabilita la connessione, prova a fare domande all'assistente AI, ad esempio:
- Quanti utenti ho avuto ieri?
- Quali sono stati i miei prodotti più venduti ieri?
- Ho un budget di marketing di 5000 $al mese e devo generare più entrate. Aiutami a creare un piano di marketing basato sui dati.
- Quali dimensioni e metriche personalizzate sono configurate nella mia proprietà?
- Quali sono gli eventi più popolari nella mia proprietà Google Analytics negli ultimi 90 giorni?
Risoluzione dei problemi
Utilizza il seguente elenco di controllo per risolvere gli errori comuni di configurazione e runtime:
403 PERMISSION_DENIED(API non abilitata o autorizzazioni della proprietà insufficienti):- Verifica che l'API Google Analytics Admin
(
analyticsadmin.googleapis.com) e l' API Google Analytics Data (analyticsdata.googleapis.com) siano abilitate nel progetto specificato daGOOGLE_CLOUD_PROJECT. - Verifica che l'utente o il service account di autenticazione disponga almeno del ruolo Visualizzatore (
roles/analytics.viewer) nella proprietà Google Analytics di destinazione nell'interfaccia utente di Google Analytics. - Se lo stato di errore è
Request had insufficient authentication scopes, esegui di nuovogcloud auth application-default logincon gli ambitihttps://www.googleapis.com/auth/analytics.readonlyehttps://www.googleapis.com/auth/cloud-platform.
- Verifica che l'API Google Analytics Admin
(
Progetto di quota mancante (
GOOGLE_CLOUD_PROJECT) o403 ACCESS_NOT_CONFIGURED:Le richieste autenticate con le credenziali ADC dell'utente richiedono un progetto di quota con le API Google Analytics abilitate. Imposta
"GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"nella configurazioneenvdel server MCP o imposta il progetto di quota nel file ADC:gcloud auth application-default set-quota-project YOUR_PROJECT_ID
401 UNAUTHENTICATEDo file delle credenziali non trovato:- Utilizza un percorso assoluto per
GOOGLE_APPLICATION_CREDENTIALS(ad esempio,/Users/username/.config/gcloud/application_default_credentials.json). Evita le variabili~o$HOME, poiché molti host MCP non espandono le variabili della shell all'interno dei file di configurazione JSON. - Esegui nuovamente
gcloud auth application-default loginse le tue credenziali utente sono scadute.
- Utilizza un percorso assoluto per
Il server non si avvia (errori
spawn pipx ENOENT,uvx: command not foundo relativi alla versione di Python):- Verifica che sia installato Python 3.10 o versioni successive (
python3 --version). - Le applicazioni GUI desktop (come Claude Desktop e Cursor) spesso non ereditano la shell interattiva
PATH. Sostituisci"pipx"o"uvx"in"command"con il percorso binario assoluto restituito dawhich pipxowhich uvx(ad esempio,/opt/homebrew/bin/pipxo/Users/username/.local/bin/pipx).
- Verifica che sia installato Python 3.10 o versioni successive (