Como criar um servidor MCP do Google Analytics

Um servidor MCP do GA4 que roda no seu notebook é trabalho para uma tarde. Um em que outras pessoas consigam fazer login é um projeto bem maior. Este guia entrega a versão de uma tarde e depois lista o que a versão grande envolve, para você decidir qual precisa.

Índice

Confira primeiro o servidor oficial

O Google publica o próprio servidor MCP do Google Analytics, ainda marcado como experimental. Ele roda no seu computador em Python, e antes de funcionar você precisa ativar a Google Analytics Admin API e a Data API em um projeto do Google Cloud. Ele já traz run_report, run_realtime_report, run_funnel_report e consultas de contas, propriedades, dimensões personalizadas e vínculos com o Google Ads. Se você só precisa do GA4, e só no seu computador, use ele:

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

A página de configuração do Google explica o projeto do Cloud passo a passo, e o README traz a linha exata de claude mcp add para o Claude Code. Não existe versão hospedada, então ele só funciona onde você consegue rodar Python.

Crie o seu quando quiser ferramentas pensadas para as suas perguntas, dados de mais de uma fonte em uma única resposta, ou um servidor que a sua equipe ou os seus clientes possam usar.

Do que você precisa

• Um projeto do Google Cloud com a Google Analytics Data API ativada (cinco minutos).
• Um ID do cliente OAuth do tipo app para computador nesse projeto, baixado como JSON. É o arquivo para o qual o --client-id-file aponta.
• Node 22 ou mais recente, que é o que o pacote atual @google-analytics/data exige.
• Acesso de Leitor à propriedade do GA4, na conta do Google com que você vai fazer login.

Passo 1: uma ferramenta que roda qualquer relatório

Comece com uma única ferramenta, run_report. O Claude já conhece os nomes de métricas e dimensões do GA4, então uma ferramenta flexível cobre a maioria das perguntas. Divida em ferramentas mais específicas depois, quando você vir quais perguntas faz de verdade.

Prepare a pasta e faça login uma vez. O segundo comando gcloud importa: as APIs do Analytics do Google recusam credenciais de usuário que não indicam um projeto de cota.

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

Depois salve isto como 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());

Não há nenhuma chave no arquivo. O cliente usa o login que o gcloud acabou de salvar, e cada chamada roda como você, com o seu acesso de Leitor.

Passo 2: adicione ao Claude

No Claude Code, um comando registra o servidor. Use o caminho completo do arquivo. --scope user deixa ele disponível em todos os seus projetos; sem essa opção, ele só carrega na pasta em que você rodou o comando:

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

Depois pergunte: “Na propriedade 123456789, quais canais trouxeram mais sessões engajadas no mês passado?” O Claude escolhe as métricas, chama a ferramenta e explica as linhas. No Claude Desktop, o mesmo servidor vai no arquivo de configuração; meu guia para criar o primeiro servidor MCP mostra onde ele fica.

Passo 3: onde complica

Tudo até aqui roda como você, no seu computador. Veja o que muda quando ele precisa rodar em qualquer outro lugar:

1. Hospedagem e OAuth. O claude.ai e o app para celular não alcançam um servidor no seu notebook. Um servidor hospedado precisa do fluxo OAuth do MCP, para que cada usuário faça login na própria conta do Google, e de um lugar seguro para guardar os refresh tokens deles.
2. A verificação de apps do Google. analytics.readonly é um escopo sensível. Até o Google verificar o seu app, todo usuário vê um aviso de “app não verificado” e você fica limitado a 100 usuários. A verificação exige uma política de privacidade no seu próprio domínio, um vídeo de demonstração do login, uma justificativa por escrito para cada escopo e uma análise.
3. Cotas. A Data API mede tokens por propriedade: 40.000 por hora e 200.000 por dia em uma propriedade padrão, com cada projeto do Cloud limitado a 14.000 por hora por propriedade e a 10 requisições simultâneas. A maioria das requisições custa 10 tokens ou menos. Períodos longos, muitas dimensões e propriedades com muito tráfego custam mais, e um agente dispara relatórios muito mais rápido do que uma pessoa clicando no GA4. Hospedado, toda chamada sai da cota do seu projeto, então adicione returnPropertyQuota: true para ver quanto cada requisição custa, guarde em cache o que se repete e mantenha os relatórios pequenos.

O SiteWide cuida da hospedagem e do login. A verificação dele no Google ainda está em andamento, então por enquanto o GA4 mostra lá a mesma tela de app não verificado. Se preferir não criar nada disso, conecte o SiteWide.

Peça ao Claude para criar

Cole isto no Claude Code, em uma pasta vazia. O prompt está em inglês, assim como o código:

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.

Antes de confiar no resultado, confira cada métrica e dimensão usada na página do esquema da API do Google. Um nome inventado parece certo no código e só falha quando a API o recusa.