Como criar um servidor MCP do Google Analytics
Teste primeiro o servidor MCP do GA4 do próprio Google: ele é experimental, roda localmente em Python e cobre o GA4 no seu computador. Para criar o seu, escreva uma ferramenta run_report com o SDK de MCP para TypeScript e o @google-analytics/data, faça login com o gcloud e o escopo analytics.readonly, e registre com claude mcp add. A parte difícil é hospedar para outras pessoas: você precisa do fluxo OAuth do MCP, da verificação do Google para um escopo sensível (apps não verificados têm limite de 100 usuários) e de cache para ficar dentro das cotas por propriedade da Data API.
Aprenda a usar agentes de IA em marketing, vendas e produto. Toda semana compartilho o que aprendi com mais de 5.400 leitores.
✓ Verifique sua caixa de entrada — clique no link de confirmação para concluir o cadastro.
✓ Inscrição concluída!
✓ Você já está na lista.
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
Abrir Í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-mcpA 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-fileaponta. - Node 22 ou mais recente, que é o que o pacote atual
@google-analytics/dataexige. - 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_IDDepois 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.tsDepois 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:
- 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.
- 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. - 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: truepara 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.
Aprenda a usar agentes de IA em marketing, vendas e produto. Toda semana compartilho o que aprendi com mais de 5.400 leitores.
✓ Verifique sua caixa de entrada — clique no link de confirmação para concluir o cadastro.
✓ Inscrição concluída!
✓ Você já está na lista.
Posts relacionados
Como ler o Search Console por idioma
O Search Console mistura todos os idiomas em um só número. Este é o filtro regex que uso para separar cliques, CTR e posição por idioma, com meus dados.
SEOComo ler o Search Console durante uma core update do Google
Uma core update está em andamento e o seu gráfico mexeu. Esta é a linha de base, os segmentos e a espera que uso antes de alterar qualquer página.
SEOImpressões subiram, CTR caiu no Search Console: o que faço
Impressões +437% em um dia, CTR −66% e posição média melhor. Veja como leio esse padrão no Search Console antes de mexer em qualquer título.
Receba o manual de IA na sua caixa de entrada
Aprenda a usar agentes de IA em marketing, vendas e produto. Toda semana compartilho o que aprendi com mais de 5.400 leitores.
Verifique sua caixa de entrada.
Enviamos um e-mail de confirmação — clique no link para concluir sua inscrição. Verifique o spam se não o vir em um minuto.
Você está inscrito.
Bem-vindo — a próxima edição chega em breve à sua caixa de entrada.
Você já está na lista — fique de olho toda quarta-feira.