EN Entrar Agendar conversa

MCP do Google Analytics 1.0: o que faz e como conectá-lo ao GA4

Por Martín Garay

Card da CookingMetrics com o título “converse com seu negócio”. Um relatório do Google Analytics se conecta por MCP a um assistente de IA. Em quatro mensagens, define-se uma comparação de vendas por fonte de tráfego e esclarece-se que também é preciso analisar os caminhos de conversão para identificar os canais de venda e os que auxiliam na conversão.
Conteúdo

O servidor MCP do Google Analytics é a via oficial para que um assistente de IA, como o Claude ou o Cursor, consulte os dados de uma propriedade do GA4 por meio das APIs do Google. Em 3 de novembro de 2026, o Google publicou a versão 1.0.0 e o projeto deixou a fase experimental. Três dias depois chegou a 1.1.0, que adiciona a criação opcional de eventos-chave e dimensões personalizadas.

Este artigo explica quais ferramentas ele inclui, como instalá-lo passo a passo e quais cuidados tomar antes de habilitar a escrita. O que se afirma sobre o funcionamento do servidor vem do repositório oficial no GitHub e da documentação do Google for Developers, consultados em 11 de novembro de 2026.

Em síntese

  • Com a 1.0.0 (3/11/2026), o projeto deixou de ser experimental. A versão vigente em 11/11/2026 é a 1.1.0.
  • Oferece quatro relatórios (padrão, tempo real, funis e conversões) e leituras de configuração: contas, propriedade, eventos-chave, dimensões e métricas personalizadas, vínculos com o Google Ads e anotações.
  • Cada resposta de um relatório retorna até 250.000 linhas; volumes maiores são paginados.
  • Vem somente com leitura. Criar anotações, eventos-chave ou dimensões personalizadas exige ativar --allow-write, adicionar o escopo analytics.edit e ter o papel adequado na propriedade.
  • Requer um projeto do Google Cloud com duas APIs habilitadas, credenciais e Python 3.10 ou superior.

O que é um servidor MCP e o que muda com a versão 1.0

MCP (Model Context Protocol) é um protocolo aberto que permite a um assistente de IA usar ferramentas externas. Um servidor MCP expõe essas ferramentas com nome, descrição e parâmetros, e o assistente decide quando chamá-las. Neste caso, as ferramentas consultam a Google Analytics Data API e a Google Analytics Admin API com as credenciais do usuário.

Na prática, em vez de montar um relatório na interface ou escrever código contra a API, a pergunta vai para o assistente, que transforma o pedido em uma consulta, a executa e devolve o resultado.

O projeto foi publicado como experimento em agosto de 2025 (versão 0.1.0). A versão 1.0.0, de 3 de novembro de 2026, o declara estável, segundo a lista de versões do repositório. A 1.1.0, de 6 de novembro, adicionou intervalos por minuto no tempo real e as ferramentas opcionais de escrita de dimensões personalizadas e eventos-chave.

O que ele pode fazer hoje

Relatórios

  • Relatório padrão (run_report). Dimensões, métricas, filtros, ordenação e intervalos de datas. Cada resposta retorna até 250.000 linhas e pode ser paginada.
  • Tempo real (run_realtime_report). Os últimos 30 minutos, ou até dois intervalos por minuto dentro dessa janela. Serve para confirmar que uma campanha recém-ativada ou uma tag corrigida já está enviando dados.
  • Funis (run_funnel_report). Etapas definidas pelo usuário, detalhamento por uma dimensão, segmentos e análise da "próxima ação": o que as pessoas fazem depois de concluir ou abandonar o funil. Usa a versão alfa da Data API, portanto pode mudar.
  • Conversões (run_conversions_report). Custos de anúncios, conversões, retorno sobre o investimento em publicidade (ROAS) e modelo de atribuição, baseado em dados (DATA_DRIVEN) ou último clique (LAST_CLICK).

Conteúdo exclusivo

Para leitores com conta

Um relatório que pode ser reconciliado

Revise uma consulta ilustrativa e um controle numérico fictício com datas, escopos e paginação explícitos.

Entre para acessar esta seção →

Trabalhamos para oferecer conteúdos da melhor qualidade; por isso algumas destas explicações não são públicas.

Auditoria da configuração

  • Resumo das contas e propriedades às quais a credencial tem acesso.
  • Detalhes de uma propriedade.
  • Lista de eventos-chave.
  • Dimensões e métricas personalizadas.
  • Contas do Google Ads vinculadas.
  • Anotações da propriedade.

Para uma auditoria, esta parte é tão útil quanto os relatórios: permite perguntar, por exemplo, quais eventos estão marcados como eventos-chave e se algum não registrou atividade nos últimos 30 dias.

Conteúdo exclusivo

Para leitores com conta

Transformar configuração em achados verificáveis

Separe observação, hipótese e próxima verificação sem tratar a falta de atividade como um erro confirmado.

Entre para acessar esta seção →

Trabalhamos para oferecer conteúdos da melhor qualidade; por isso algumas destas explicações não são públicas.

Configuração (somente com a escrita ativada)

  • Criar anotações na linha do tempo da propriedade.
  • Criar dimensões personalizadas (requer o papel de Editor).
  • Marcar um evento como evento-chave (requer o papel de Profissional de marketing ou Editor).

Essas três ferramentas não ficam disponíveis se o servidor não for iniciado com a escrita ativada.

Pré-requisitos

  • Um projeto do Google Cloud.
  • A Google Analytics Admin API e a Google Analytics Data API habilitadas nesse projeto.
  • Acesso à propriedade com, no mínimo, o papel de Leitor.
  • Credenciais com o escopo https://www.googleapis.com/auth/analytics.readonly. Para escrever, também https://www.googleapis.com/auth/analytics.edit.
  • Python 3.10 ou superior e pipx (ou uv) para executar o pacote analytics-mcp.

Como instalar passo a passo

  1. Habilitar as APIs. Pelo console do Google Cloud ou com a CLI do Google Cloud:

    gcloud services enable analyticsadmin.googleapis.com analyticsdata.googleapis.com --project=ID_DO_PROJETO

  2. Configurar as credenciais. A opção mais direta são as credenciais padrão do aplicativo (ADC):

    gcloud auth application-default login --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

    O comando informa o caminho do arquivo de credenciais que gera. Como alternativa, é possível usar uma conta de serviço, por personificação ou com um arquivo de chave, que recebe acesso à propriedade como qualquer usuário.

  3. Adicionar o servidor ao assistente. No Claude Code:

    claude mcp add analytics-mcp --scope user -e GOOGLE_APPLICATION_CREDENTIALS="CAMINHO_DO_ARQUIVO_JSON" -e GOOGLE_CLOUD_PROJECT="ID_DO_PROJETO" -- pipx run analytics-mcp

    No Claude Desktop, no Cursor ou em outros clientes compatíveis, a configuração equivalente em JSON é:

    {
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "CAMINHO_DO_ARQUIVO_JSON",
        "GOOGLE_CLOUD_PROJECT": "ID_DO_PROJETO"
      }
    }
  }
}

  4. Verificar a conexão. Reiniciar o cliente e pedir algo de baixo risco, por exemplo: "A quais contas e propriedades do Google Analytics eu tenho acesso?". Se a resposta listar as propriedades esperadas, a conexão funciona.

O repositório também documenta a execução como servidor HTTP próprio, inclusive no Cloud Run, com OAuth integrado. O Google não oferece um servidor hospedado: cada equipe executa o seu.

Conteúdo exclusivo

Para leitores com conta

Uma conexão que pode ser repetida

Documente versão, escopo e testes de leitura com uma matriz de diagnóstico que evita compartilhar credenciais.

Entre para acessar esta seção →

Trabalhamos para oferecer conteúdos da melhor qualidade; por isso algumas destas explicações não são públicas.

Conteúdo exclusivo

Para leitores com conta

Três pedidos com um contrato de evidências

Use modelos para ecommerce, aquisição e funis que exijam definição, consulta, limites e resultados verificáveis.

Entre para acessar esta seção →

Trabalhamos para oferecer conteúdos da melhor qualidade; por isso algumas destas explicações não são públicas.

Prompts para começar

  • "Compare sessões e eventos-chave da Meta com os do Google Ads nos últimos 30 dias, em relação ao período anterior." O resultado depende de como o tráfego da Meta está marcado: sem parâmetros UTM consistentes, parte desse tráfego pode aparecer como referência ou direto.
  • "Mostre o funil de compra somente do tráfego pago. Em qual etapa mais pessoas desistem e o que fazem depois?" O assistente precisa definir um segmento de tráfego pago; convém pedir que informe a condição usada.
  • "O tráfego da campanha ativada hoje está chegando em tempo real?"
  • "Adicione uma anotação com a data de hoje: a estratégia de lances foi alterada para ROAS desejado." Só funciona com a escrita ativada.

Em todos os casos, convém pedir ao assistente que mostre as dimensões, métricas, filtros e datas que usou. Um relatório correto com uma definição errada continua sendo um erro.

Por que começar somente com leitura

A escrita é ativada de propósito, com a opção --allow-write ou a variável de ambiente ANALYTICS_MCP_ALLOW_WRITE, e também exige o escopo analytics.edit. Mantê-la desativada no início tem três vantagens:

  • Dano limitado. Um pedido ambíguo não consegue criar eventos-chave nem dimensões. Um evento-chave muda o que os relatórios contam como conversão e, se a propriedade estiver vinculada, o que pode chegar ao Google Ads.
  • Cotas limitadas. As propriedades têm um número máximo de dimensões personalizadas. Criar uma de teste ocupa uma vaga.
  • Processo. Antes de delegar mudanças a um assistente, a equipe precisa definir quem as aprova e como são registradas.

Quando a escrita for necessária, convém usar uma credencial separada, limitada às propriedades correspondentes, e começar pelas anotações, que não alteram os dados.

Conteúdo exclusivo

Para leitores com conta

Avaliar uma escrita antes de habilitá-la

Prepare uma mudança concreta com escopo, necessidade, permissões e recuperação antes de solicitar aprovação.

Entre para acessar esta seção →

Trabalhamos para oferecer conteúdos da melhor qualidade; por isso algumas destas explicações não são públicas.

Limites que convém conhecer

  • Documentação desalinhada. Em 11 de novembro de 2026, a página do Google for Developers informa que o servidor está disponível somente para leitura e lista nove ferramentas; o repositório, na versão 1.1.0, inclui treze, três delas de escrita opcional.
  • Funções em versão alfa. Os funis e as anotações usam versões alfa das APIs do Google, que podem mudar.
  • Cotas. As consultas consomem a cota da Data API do projeto. Muitas perguntas encadeadas sobre intervalos amplos podem esgotá-la.
  • Interpretação. O servidor devolve dados; a conclusão é montada pelo assistente. Os números devem ser verificados antes de serem usados em uma decisão ou em um relatório para um cliente.

As respostas do assistente valem tanto quanto a configuração da propriedade. Se os eventos, as conversões ou a atribuição de campanhas não estiverem bem definidos, o autodiagnóstico de Google Analytics da CookingMetrics ajuda a revisá-los antes de confiar em uma consulta automática.

Leituras relacionadas

Perguntas frequentes

O MCP do Google Analytics modifica a propriedade?

Não, a menos que a escrita seja ativada de forma explícita. Por padrão, ele só consulta relatórios e configuração. Com --allow-write e o escopo analytics.edit, pode criar anotações, eventos-chave e dimensões personalizadas, de acordo com o papel da credencial na propriedade.

É preciso saber programar para usá-lo?

Para consultá-lo, não: as perguntas são feitas em linguagem natural. A instalação, porém, exige trabalhar com o console do Google Cloud, a linha de comando e o arquivo de configuração do cliente de IA.

O Google oferece um servidor hospedado?

Não. O servidor é executado na máquina do usuário ou em uma infraestrutura própria, como o Cloud Run. O repositório documenta as duas opções.

MCP do Google Analytics 1.0: o que faz e como conectá-lo ao GA4

Ver o diagnóstico do meu GA4