Come creare un server MCP per Google Analytics

Un server MCP per GA4 che gira sul tuo portatile è il lavoro di un pomeriggio. Uno a cui possono accedere altre persone è un progetto molto più grande. Questa guida ti dà la versione da un pomeriggio, poi elenca cosa comporta quella grande, così puoi decidere quale ti serve.

Indice

Prima guarda il server ufficiale

Google pubblica un suo server MCP per Google Analytics, ancora segnato come sperimentale. Gira sul tuo computer in Python, e prima che funzioni devi attivare la Google Analytics Admin API e la Data API in un progetto Google Cloud. Ha già run_report, run_realtime_report, run_funnel_report e ricerche su account, proprietà, dimensioni personalizzate e collegamenti a Google Ads. Se ti serve solo GA4, e solo sul tuo computer, usa quello:

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_FILE

pipx run analytics-mcp

La pagina di configurazione di Google spiega il progetto Cloud passo per passo, e il README riporta la riga claude mcp add esatta per Claude Code. Non esiste una versione ospitata, quindi funziona solo dove puoi eseguire Python.

Creane uno tuo quando vuoi strumenti pensati per le tue domande, dati da più fonti in una sola risposta, o un server che possano usare il tuo team o i tuoi clienti.

Cosa ti serve

• Un progetto Google Cloud con la Google Analytics Data API attivata (cinque minuti).
• Un ID client OAuth di tipo app desktop in quel progetto, scaricato come JSON. È il file a cui punta --client-id-file.
• Node 22 o successivo, richiesto dalla versione attuale del pacchetto @google-analytics/data.
• Accesso da Visualizzatore alla proprietà GA4, sull’account Google con cui accederai.

Passo 1: uno strumento che esegue qualsiasi report

Parti da un solo strumento, run_report. Claude conosce già i nomi di metriche e dimensioni di GA4, quindi uno strumento flessibile copre quasi tutte le domande. Dividilo in strumenti più specifici in seguito, quando vedrai quali domande fai davvero.

Prepara la cartella e accedi una volta. Il secondo comando gcloud conta: le API di Analytics di Google rifiutano le credenziali utente che non indicano un progetto di quota.

mkdir ga4-mcp && cd ga4-mcp
npm init -y && npm pkg set type=module
npm install @modelcontextprotocol/sdk @google-analytics/data zod

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_FILE
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Poi salva questo come ga4.ts:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { BetaAnalyticsDataClient } from '@google-analytics/data';
import { z } from 'zod';

const ga = new BetaAnalyticsDataClient(); // Application Default Credentials
const server = new McpServer({ name: 'ga4', version: '1.0.0' });

server.registerTool(
  'run_report',
  {
    description:
      'Run a GA4 report. Uses GA4 Data API metric and dimension names. ' +
      'Dates accept YYYY-MM-DD, "28daysAgo", "yesterday", "today".',
    inputSchema: {
      propertyId: z.string().describe('Numeric GA4 property ID, e.g. 123456789'),
      metrics: z.array(z.string()).describe('e.g. ["sessions", "engagedSessions"]'),
      dimensions: z.array(z.string()).default([]).describe('e.g. ["sessionDefaultChannelGroup"]'),
      startDate: z.string().default('28daysAgo'),
      endDate: z.string().default('today'),
    },
  },
  async ({ propertyId, metrics, dimensions, startDate, endDate }) => {
    const [res] = await ga.runReport({
      property: `properties/${propertyId}`,
      dateRanges: [{ startDate, endDate }],
      metrics: metrics.map((name) => ({ name })),
      dimensions: dimensions.map((name) => ({ name })),
      limit: 100,
    });
    // Turn GA's nested rows into plain { dimension: value, metric: value } objects.
    const rows = (res.rows ?? []).map((row) => {
      const out: Record<string, string> = {};
      row.dimensionValues?.forEach((v, i) => (out[dimensions[i]] = v.value ?? ''));
      row.metricValues?.forEach((v, i) => (out[metrics[i]] = v.value ?? ''));
      return out;
    });
    return { content: [{ type: 'text', text: JSON.stringify({ rowCount: res.rowCount, rows }) }] };
  },
);

await server.connect(new StdioServerTransport());

Nel file non c’è nessuna chiave. Il client usa l’accesso che gcloud ha appena salvato, e ogni chiamata viene eseguita a tuo nome, con il tuo accesso da Visualizzatore.

Passo 2: aggiungilo a Claude

In Claude Code basta un comando per registrarlo. Usa il percorso completo del file. --scope user lo rende disponibile in tutti i tuoi progetti; senza questa opzione si carica solo nella cartella in cui hai eseguito il comando:

claude mcp add --scope user ga4 -- npx -y tsx /full/path/to/ga4-mcp/ga4.ts

Poi chiedi: “Per la proprietà 123456789, quali canali hanno portato più sessioni con interazione il mese scorso?” Claude sceglie le metriche, chiama lo strumento e ti spiega le righe. In Claude Desktop lo stesso server va invece nel file di configurazione; la mia guida per creare il primo server MCP mostra dove si trova.

Passo 3: dove si complica

Tutto quello che hai visto finora gira a tuo nome, sul tuo computer. Ecco cosa cambia quando deve girare da qualsiasi altra parte:

1. Hosting e OAuth. claude.ai e l’app mobile non possono raggiungere un server sul tuo portatile. Un server ospitato ha bisogno del flusso OAuth di MCP, così ogni utente accede con il proprio account Google, e di un posto sicuro in cui conservare i loro refresh token.
2. La verifica delle app di Google. analytics.readonly è uno scope sensibile. Finché Google non verifica la tua app, ogni utente vede un avviso di “app non verificata” e hai un limite di 100 utenti. La verifica richiede un’informativa sulla privacy sul tuo dominio, un video dimostrativo dell’accesso, una giustificazione scritta per ogni scope e una revisione.
3. Quote. La Data API conteggia i token per proprietà: 40.000 l’ora e 200.000 al giorno per una proprietà standard, con un massimo di 14.000 l’ora per proprietà per ogni progetto Cloud e 10 richieste in contemporanea. La maggior parte delle richieste costa 10 token o meno. Intervalli di date lunghi, molte dimensioni e proprietà con molto traffico costano di più, e un agente lancia report molto più in fretta di una persona che clicca in GA4. Una volta ospitato, ogni chiamata esce dalla quota del tuo progetto: aggiungi returnPropertyQuota: true per vedere quanto costa ogni richiesta, metti in cache ciò che si ripete e tieni i report piccoli.

SiteWide si occupa dell’hosting e dell’accesso. La sua verifica con Google è ancora in corso, quindi per ora anche lì GA4 mostra la stessa schermata di app non verificata. Se preferisci non costruire niente di tutto questo, collega SiteWide.

Chiedi a Claude di crearlo

Incolla questo in Claude Code, in una cartella vuota. Il prompt è in inglese, come il codice:

Build me a TypeScript MCP server for Google Analytics 4 using @modelcontextprotocol/sdk and @google-analytics/data. Give it one tool, run_report, that takes a property id, metrics, dimensions and a date range. Authenticate with Application Default Credentials. Then give me the exact gcloud command to log in with the analytics.readonly scope, and register the server with `claude mcp add`. Don't invent metric names: link me to Google's API schema page so I can check them.

Prima di fidarti del risultato, controlla ogni metrica e dimensione che usa sulla pagina dello schema dell’API di Google. Un nome inventato sembra a posto nel codice e fallisce solo quando l’API lo rifiuta.