Servidores MCP: Tornando o Google Analytics Realmente Útil para Desenvolvedores

O Google Analytics sempre foi uma ferramenta de marketing que desenvolvedores toleram. Você configura o rastreamento, configura eventos e depois entrega para alguém que realmente gosta de clicar em dashboards. Quando você precisa de dados — taxas de rejeição para uma página específica, funis de conversão para uma nova feature, usuários ativos em tempo real segmentados por país — você acaba clicando em cinco menus aninhados, lutando com o construtor de consultas do GA4 e se perguntando por que leva mais esforço fazer uma pergunta do que respondê-la.

O Model Context Protocol muda isso completamente. Ao encapsular a API de relatórios do GA4 em um servidor MCP, você pode consultar seus dados de analytics conversacionalmente através do Claude ou qualquer assistente de IA compatível com MCP. Sem dashboards. Sem construtores de consulta. Apenas pergunte o que quer saber.

O Que É MCP e Por Que Importa

O Model Context Protocol é um padrão aberto criado pela Anthropic que define como assistentes de IA interagem com fontes de dados e ferramentas externas. Pense nele como uma porta USB-C para IA — uma interface universal que permite que qualquer assistente compatível se conecte a qualquer fonte de dados compatível sem código de integração customizado para cada combinação.

Antes do MCP, conectar um assistente de IA aos seus dados de analytics significava construir um pipeline sob medida: exportar dados para CSV, colar em um chat, torcer para que a janela de contexto seja grande o suficiente. Ou construir uma integração de API customizada, escrever templates de prompt, lidar com autenticação você mesmo. Cada nova fonte de dados exigia uma nova integração.

O MCP padroniza isso em três conceitos:

• Resources — dados estruturados que o servidor expõe (suas propriedades GA4, relatórios, dimensões, métricas)
• Tools — ações que a IA pode invocar (executar um relatório, consultar dados em tempo real, listar métricas disponíveis)
• Prompts — templates de prompt reutilizáveis que o servidor fornece (consultas de analytics comuns pré-estruturadas para bons resultados)

O servidor lida com autenticação, busca de dados e formatação de resposta. O assistente de IA lida com compreensão de linguagem natural e interpretação de resultados. Nenhum dos lados precisa conhecer os detalhes de implementação do outro.

Por Que Isso Importa Especificamente para Analytics

Plataformas de analytics são ricas em informação mas pobres em interação. O GA4 tem dados extraordinariamente poderosos — ele rastreia cada sessão de usuário, cada visualização de página, cada evento, cada conversão em todo o seu produto. Mas acessar esses dados requer que você pense no vocabulário do GA4: dimensões, métricas, segmentos, intervalos de datas, filtros, comparações. Você precisa traduzir sua pergunta para o modelo de consulta do GA4 antes de poder obter uma resposta.

Um servidor MCP inverte isso. Você faz sua pergunta em linguagem natural. A IA traduz para as chamadas de API corretas, executa-as e interpreta os resultados. A fricção entre "eu tenho uma pergunta" e "eu tenho uma resposta" cai de minutos para segundos.

Construindo um Servidor MCP para GA4

A implementação envolve três camadas: o framework do servidor MCP, o cliente da API de Dados do Google Analytics e a lógica de conexão que mapeia intenção de linguagem natural para chamadas de API.

Configuração do Projeto

mkdir ga4-mcp-server
cd ga4-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk @google-analytics/data zod dotenv
npm install -D typescript @types/node

O pacote @modelcontextprotocol/sdk fornece o framework do servidor. @google-analytics/data é a biblioteca cliente oficial do Google para a API de Dados do GA4 (a API de relatórios, não a API de Admin). zod lida com validação de entrada para parâmetros de ferramentas.

Autenticação com o Google

A autenticação da API do GA4 usa uma conta de serviço do Google Cloud. Crie uma no Google Cloud Console, baixe o arquivo de chave JSON e conceda acesso de "Visualizador" à sua propriedade GA4.

// src/analytics-client.ts
import { BetaAnalyticsDataClient } from "@google-analytics/data";

const analyticsClient = new BetaAnalyticsDataClient({
  keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS,
});

const propertyId = process.env.GA4_PROPERTY_ID;

export async function runReport(
  dimensions: string[],
  metrics: string[],
  startDate: string,
  endDate: string,
  dimensionFilter?: Record<string, string>
) {
  const request: any = {
    property: `properties/${propertyId}`,
    dimensions: dimensions.map((d) => ({ name: d })),
    metrics: metrics.map((m) => ({ name: m })),
    dateRanges: [{ startDate, endDate }],
  };

  if (dimensionFilter) {
    const filterKey = Object.keys(dimensionFilter)[0];
    request.dimensionFilter = {
      filter: {
        fieldName: filterKey,
        stringFilter: {
          value: dimensionFilter[filterKey],
          matchType: "EXACT",
        },
      },
    };
  }

  const [response] = await analyticsClient.runReport(request);
  return formatReportResponse(response);
}

function formatReportResponse(response: any) {
  if (!response.rows || response.rows.length === 0) {
    return { data: [], summary: "No data found for the specified query." };
  }

  const headers = [
    ...(response.dimensionHeaders?.map((h: any) => h.name) ?? []),
    ...(response.metricHeaders?.map((h: any) => h.name) ?? []),
  ];

  const rows = response.rows.map((row: any) => {
    const values = [
      ...(row.dimensionValues?.map((v: any) => v.value) ?? []),
      ...(row.metricValues?.map((v: any) => v.value) ?? []),
    ];
    return Object.fromEntries(headers.map((h, i) => [h, values[i]]));
  });

  return {
    data: rows,
    rowCount: response.rowCount,
    summary: `Returned ${rows.length} rows.`,
  };
}

O Servidor MCP

// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { runReport, getRealtimeData, getAvailableMetrics } from "./analytics-client";

const server = new McpServer({
  name: "ga4-analytics",
  version: "1.0.0",
});

// Tool: Run a custom report
server.tool(
  "run_report",
  "Run a Google Analytics 4 report with specified dimensions, metrics, and date range",
  {
    dimensions: z.array(z.string()).describe("GA4 dimensions like 'pagePath', 'country', 'deviceCategory'"),
    metrics: z.array(z.string()).describe("GA4 metrics like 'activeUsers', 'sessions', 'bounceRate'"),
    startDate: z.string().describe("Start date in YYYY-MM-DD format or relative like '7daysAgo'"),
    endDate: z.string().describe("End date in YYYY-MM-DD format or 'today'"),
    filter: z.record(z.string()).optional().describe("Optional dimension filter as key-value pair"),
  },
  async ({ dimensions, metrics, startDate, endDate, filter }) => {
    const result = await runReport(dimensions, metrics, startDate, endDate, filter);
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);

// Tool: Get real-time active users
server.tool(
  "realtime_users",
  "Get current real-time active users, optionally segmented by a dimension",
  {
    dimension: z.string().optional().describe("Optional dimension to segment by, like 'country' or 'pagePath'"),
  },
  async ({ dimension }) => {
    const result = await getRealtimeData(dimension);
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);

// Tool: List available metrics and dimensions
server.tool(
  "list_metrics",
  "List all available GA4 metrics and dimensions for the connected property",
  {},
  async () => {
    const result = await getAvailableMetrics();
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);

// Resource: Property metadata
server.resource(
  "property-info",
  "ga4://property/info",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: "application/json",
      text: JSON.stringify({
        propertyId: process.env.GA4_PROPERTY_ID,
        description: "Connected GA4 property for analytics queries",
      }),
    }],
  })
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

Isso dá ao assistente de IA três ferramentas: executar relatórios arbitrários, verificar dados em tempo real e descobrir quais métricas e dimensões estão disponíveis. A ferramenta de descoberta é importante — ela permite que a IA descubra os nomes de campos corretos sem que você precise lembrar se é activeUsers ou active_users ou totalUsers.

Endpoint de Dados em Tempo Real

// Added to analytics-client.ts
export async function getRealtimeData(dimension?: string) {
  const request: any = {
    property: `properties/${propertyId}`,
    metrics: [{ name: "activeUsers" }],
  };

  if (dimension) {
    request.dimensions = [{ name: dimension }];
  }

  const [response] = await analyticsClient.runRealtimeReport(request);
  return formatReportResponse(response);
}

Dados em tempo real são uma das funcionalidades de maior valor. Em um dashboard, você navegaria até a seção de tempo real, esperaria carregar e leria números. Pelo MCP, você digita "quantas pessoas estão no site agora?" e recebe uma resposta em dois segundos.

Consultas Reais que Desenvolvedores Querem Executar

Capacidades teóricas são entediantes. Aqui estão as consultas reais que me pego executando diariamente, e como elas se parecem como solicitações conversacionais para a IA:

Análise de Tráfego

"Quais são as 10 páginas com mais sessões esta semana, e como cada uma se compara à semana passada?"

A IA traduz isso em duas chamadas runReport — uma para a semana atual, uma para a semana anterior — então calcula o delta e apresenta uma tabela comparativa. Na interface do GA4, isso requer configurar um intervalo de datas de comparação, selecionar o relatório certo, adicionar a dimensão de página, ordenar por sessões e limitar a 10. Pelo MCP, é uma frase.

"Mostre o tráfego de busca orgânica nos últimos 30 dias, dividido por landing page."

Isso se torna um único relatório com sessionDefaultChannelGroup como filtro de dimensão (filtrado para "Organic Search"), landingPagePlusQueryString como dimensão, e sessions mais engagedSessions como métricas.

Depuração de Conversão

"Qual é a taxa de rejeição em /pricing comparada com /features nas últimas duas semanas?"

Duas chamadas de relatório filtradas, resultados comparados lado a lado. Este é o tipo de pergunta que leva 30 segundos para fazer conversacionalmente e 3 minutos para responder pela interface do GA4.

"Quais países têm a maior taxa de conversão para o evento de cadastro?"

Um único relatório com dimensão country, métrica eventCount filtrada para o evento sign_up, e sessions para calcular a taxa de conversão. A IA pode até fazer a divisão e apresentar porcentagens diretamente.

Monitoramento de Performance

"Qual é o tempo médio de engajamento por sessão em mobile vs desktop este mês?"

Segmentado por deviceCategory, medindo averageSessionDuration e engagedSessions. Consulta simples, mas que requer navegar até o relatório certo e configurar segmentos no GA4.

"Existem páginas com mais de 1000 visualizações esta semana mas com taxa de engajamento abaixo de 30%?"

É aqui que a analytics conversacional realmente brilha. A IA executa o relatório, filtra os resultados programaticamente e retorna apenas as páginas que atendem ambos os critérios. No GA4, você precisaria exportar para uma planilha e filtrar manualmente, ou construir uma exploração customizada.

Conectando ao Claude e Assistentes de IA

Configuração do Claude Desktop

Uma vez que seu servidor MCP está construído, conectá-lo ao Claude Desktop é uma edição de arquivo de configuração:

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "node",
      "args": ["/path/to/ga4-mcp-server/dist/server.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

No macOS, isso vai em ~/Library/Application Support/Claude/claude_desktop_config.json. No Windows, é %APPDATA%\Claude\claude_desktop_config.json.

Após reiniciar o Claude Desktop, as ferramentas GA4 aparecem no menu de ferramentas. O Claude agora pode chamá-las diretamente na conversa.

Integração com Claude Code

Para desenvolvedores que trabalham principalmente no terminal, o Claude Code suporta servidores MCP nativamente. Adicione o servidor ao .mcp.json do seu projeto:

{
  "mcpServers": {
    "ga4-analytics": {
      "command": "node",
      "args": ["./mcp-servers/ga4/dist/server.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "./credentials/ga4-service-account.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

Agora você pode consultar dados de analytics sem sair do seu editor. Enquanto debugga uma regressão de performance, você pode perguntar "qual é a taxa de rejeição em /checkout esta semana vs semana passada?" sem trocar de contexto para um navegador.

Usando com Outros Clientes Compatíveis com MCP

A beleza do MCP como padrão é que qualquer cliente compatível funciona. Cursor, Windsurf e outros editores com suporte a MCP podem se conectar ao mesmo servidor. Você constrói o servidor uma vez e ele funciona em todos os lugares.

Exemplos Práticos de Analytics Conversacional

Deixe-me mostrar um workflow real que uso regularmente.

Check-In Matinal

Eu começo o dia perguntando ao Claude: "Me dê um resumo do tráfego de ontem — total de sessões, usuários ativos, top 5 páginas, e quaisquer páginas com taxa de engajamento abaixo de 25%."

A IA faz três chamadas de ferramenta: uma para métricas gerais, uma para top páginas, uma para páginas com baixo engajamento. Ela retorna algo como:

Ontem: 2.341 sessões de 1.892 usuários únicos. As top páginas foram /home (580 sessões), /pricing (412), /docs/getting-started (389), /blog/mcp-guide (267), /features (198). Duas páginas tiveram engajamento abaixo de 25%: /legal/terms (12%) e /blog/old-post-2024 (22%).

Isso levaria 5-10 minutos na interface do GA4. Pelo MCP, leva 15 segundos.

Monitoramento de Lançamento de Feature

Quando lanço uma nova feature, quero saber se as pessoas estão encontrando e usando. "Compare o tráfego para /features/new-dashboard nos últimos 3 dias vs os 3 dias antes do lançamento, dividido por canal de aquisição."

A IA executa a comparação, identifica quais canais estão impulsionando a descoberta (geralmente direto e busca orgânica ficam atrás de social e referência nos primeiros dias após o lançamento) e destaca quaisquer anomalias.

Depurando Reclamações de Usuários

Quando usuários relatam que "o site parece lento", eu posso perguntar: "Qual é o tempo médio de carregamento da página por página nos últimos 7 dias, ordenado do mais lento primeiro?" Se o GA4 tem dados de Web Vitals (via protocolo de medição ou eventos gtag), o servidor MCP pode trazer isso sem eu abrir um navegador.

Relatório Semanal

"Gere uma comparação semana a semana de sessões, novos usuários, taxa de engajamento e taxa de conversão para cada uma das nossas top 20 páginas."

Isso produz uma tabela formatada que posso colocar diretamente em uma mensagem do Slack ou atualização de equipe. Sem ginásticas de planilha, sem recorte de screenshots.

Construindo Funcionalidades Avançadas

Camada de Cache

A API do GA4 tem limites de taxa (tipicamente 10 requisições por minuto por propriedade para o tier gratuito). Para um servidor MCP que pode ser consultado frequentemente, adicione uma camada de cache:

import { createHash } from "crypto";

const cache = new Map<string, { data: any; expiry: number }>();

function getCacheKey(dimensions: string[], metrics: string[], startDate: string, endDate: string): string {
  const input = JSON.stringify({ dimensions, metrics, startDate, endDate });
  return createHash("md5").update(input).digest("hex");
}

export async function cachedRunReport(
  dimensions: string[],
  metrics: string[],
  startDate: string,
  endDate: string
) {
  const key = getCacheKey(dimensions, metrics, startDate, endDate);
  const cached = cache.get(key);

  if (cached && cached.expiry > Date.now()) {
    return cached.data;
  }

  const result = await runReport(dimensions, metrics, startDate, endDate);

  // Cache for 5 minutes (real-time queries get shorter TTL)
  const ttl = startDate === "today" ? 60_000 : 300_000;
  cache.set(key, { data: result, expiry: Date.now() + ttl });

  return result;
}

Consultas em tempo real recebem TTL de 1 minuto. Consultas históricas recebem 5 minutos. Isso mantém você bem dentro dos limites de taxa durante uma sessão conversacional onde a IA pode fazer várias consultas relacionadas em rápida sucessão.

Suporte a Múltiplas Propriedades

Se você gerencia múltiplos produtos ou clientes, estenda o servidor para suportar alternância entre propriedades GA4:

server.tool(
  "switch_property",
  "Switch to a different GA4 property",
  {
    propertyId: z.string().describe("The GA4 property ID to switch to"),
  },
  async ({ propertyId }) => {
    // Validate access
    const properties = await listAccessibleProperties();
    if (!properties.includes(propertyId)) {
      return {
        content: [{ type: "text", text: `No access to property ${propertyId}` }],
      };
    }

    currentPropertyId = propertyId;
    return {
      content: [{ type: "text", text: `Switched to property ${propertyId}` }],
    };
  }
);

Agora você pode dizer "mude para a propriedade de staging e mostre o tráfego de ontem" sem reconfigurar nada.

Considerações de Segurança

Executar um servidor MCP que acessa dados de analytics introduz várias preocupações de segurança que precisam de tratamento deliberado.

Gerenciamento de Credenciais

O arquivo de chave da conta de serviço é a peça mais sensível. Nunca o comite no controle de versão. Use variáveis de ambiente ou um gerenciador de secrets. Se você está executando o servidor MCP localmente (que é o caso comum para Claude Desktop), armazene o arquivo de chave fora do diretório do projeto com permissões restritas de arquivo:

chmod 600 /path/to/service-account-key.json

Para ambientes de equipe, considere usar o Workload Identity Federation do Google Cloud em vez de um arquivo de chave. Ele elimina a credencial estática completamente usando tokens de curta duração vinculados à identidade de tempo de execução.

Princípio do Menor Privilégio

A conta de serviço deve ter acesso somente leitura ao GA4. Especificamente, conceda a função "Visualizador" no nível da propriedade GA4 — não a função "Editor" ou "Administrador". O servidor MCP nunca precisa modificar sua configuração de analytics, criar audiências ou alterar configurações de medição.

No nível do projeto Google Cloud, conceda apenas o escopo analyticsdata.readonly. Isso impede que a conta de serviço acesse quaisquer outros serviços do Google Cloud mesmo se a chave for comprometida.

Escopo de Exposição de Dados

Seja deliberado sobre quais dados o servidor MCP pode acessar. O GA4 pode conter informações pessoais — IDs de usuário, IDs de cliente, geolocalização derivada de IP. Seu servidor MCP deve remover ou mascarar campos que não são necessários para as consultas que você quer suportar.

const BLOCKED_DIMENSIONS = ["userID", "clientId"];

function validateDimensions(dimensions: string[]) {
  const blocked = dimensions.filter((d) => BLOCKED_DIMENSIONS.includes(d));
  if (blocked.length > 0) {
    throw new Error(`Blocked dimensions for privacy: ${blocked.join(", ")}`);
  }
}

Isso é especialmente importante se outros membros da equipe podem interagir com o servidor MCP. Você quer prevenir consultas casuais que poderiam expor dados individuais de usuários.

Segurança de Transporte

O MCP atualmente roda sobre stdio (entrada/saída padrão) quando usado com Claude Desktop, o que significa que a comunicação acontece dentro dos limites de processos locais. Não há exposição de rede. Porém, se você implantar um servidor MCP sobre HTTP (usando o transporte SSE), você precisa de TLS, tokens de autenticação e limitação de taxa — trate-o como qualquer outro endpoint de API.

Log de Auditoria

Registre cada consulta que o servidor MCP processa. Não apenas por segurança — por responsabilidade. Quando alguém perguntar "quem consultou nossos dados de analytics e quando", você deve ter uma resposta.

function logQuery(tool: string, params: Record<string, unknown>) {
  console.log(JSON.stringify({
    timestamp: new Date().toISOString(),
    tool,
    params,
    propertyId: currentPropertyId,
  }));
}

Trade-Offs e Limitações

O Que Funciona Bem

A analytics conversacional elimina a curva de aprendizado do GA4 para desenvolvedores. Você não precisa conhecer os nomes de dimensões e métricas do GA4, tipos de relatório ou sintaxe de filtro. A IA lida com a tradução. Para perguntas ad-hoc — do tipo que você faz uma vez e nunca repete — isso é dramaticamente mais rápido que o dashboard.

Combinar analytics com contexto de desenvolvimento é poderoso. Quando você está debugando no Claude Code e pode simultaneamente verificar dados de analytics, o ciclo de feedback se estreita. Você vê o código, os logs de erro e o impacto nos usuários em um só lugar.

O Que Não Funciona Bem

Explorações complexas que requerem refinamento iterativo ainda são mais rápidas na interface Explore do GA4. Se você está construindo uma análise de funil com múltiplos estágios, segmentos customizados e grupos de comparação, o construtor visual dá feedback imediato que uma interface conversacional não consegue igualar.

Dashboards em tempo real que atualizam automaticamente estão fora do modelo atual do MCP. O MCP é request-response — você pergunta, ele responde. Para um dashboard que atualiza ao vivo mostrando usuários em tempo real, uma ferramenta dedicada como a visualização em tempo real do GA4 ou um painel customizado do Grafana é melhor.

Volume de dados é uma restrição. A API de Dados do GA4 retorna até 100.000 linhas por requisição. Para propriedades com milhões de eventos diários, você pode precisar ser específico sobre dimensões e intervalos de datas para evitar atingir esse limite. A API também tem comportamento de amostragem para datasets grandes — resultados podem ser estimados em vez de exatos para consultas de alta cardinalidade.

MCP vs. Integração Direta de API

Se você está construindo uma feature de produto que precisa de dados de analytics (como um dashboard de admin para seu SaaS), use a API do GA4 diretamente. O MCP é para consultas com humano no loop, não pipelines de dados programáticos. O overhead de tradução de linguagem natural e interpretação por IA é desnecessário quando você sabe exatamente qual consulta executar.

O MCP brilha quando a pergunta é desestruturada, quando você não sabe exatamente o que está procurando, ou quando o esforço de construir uma integração adequada não se justifica para uma pergunta pontual. É o equivalente em analytics de abrir um REPL em vez de escrever um script.

Começando

Se você quer experimentar isso, o caminho mínimo é:

1. Crie um projeto Google Cloud e habilite a API de Dados do Google Analytics.
2. Crie uma conta de serviço com acesso de Visualizador à sua propriedade GA4.
3. Baixe o JSON da chave da conta de serviço.
4. Clone ou construa o servidor MCP como descrito acima.
5. Adicione o servidor à sua configuração do Claude Desktop ou Claude Code.
6. Comece a fazer perguntas.

Toda a configuração leva cerca de 30 minutos se você já tem uma propriedade GA4. O retorno é imediato — a primeira vez que você recebe uma resposta para uma pergunta de analytics em 5 segundos em vez de 5 minutos, você não vai querer voltar ao dashboard.

Dados de analytics são um dos ativos mais subutilizados na maioria dos times de desenvolvimento. Não porque não são valiosos, mas porque acessá-los sempre foi inconveniente o suficiente para desencorajar consultas casuais. O MCP remove essa fricção. Os dados são os mesmos. As perguntas são as mesmas. O tempo para responder é o que muda.