Como usar o Google Analytics MCP no OpenCode para consultar o GA4

Abrir o Google Analytics no navegador resolve uma pergunta pontual. Você escolhe a conta, encontra a propriedade correta, abre um relatório, troca o intervalo de datas, adiciona dimensões, ajusta métricas e copia os números para algum lugar onde consiga compará-los com a semana passada. Quando a pergunta muda um pouco, o caminho começa de novo.

O problema não é a interface. Ela é útil para exploração visual. A dor aparece quando a consulta precisa ser repetida, explicada para outra pessoa ou combinada com contexto que está fora do GA4: uma versão publicada, uma campanha, um teste de aquisição ou uma mudança no produto. A sequência de cliques não é uma especificação da consulta. Duas pessoas podem abrir relatórios parecidos e sair com números diferentes porque escolheram propriedades, filtros ou fusos horários diferentes.

Foi esse o caso ao configurar o Google Analytics MCP Server no OpenCode. O ganho não foi transformar o GA4 em uma conversa mágica. Foi dar ao agente acesso a ferramentas que chamam as APIs oficiais, descobrem as propriedades disponíveis e executam relatórios com dimensões, métricas e períodos explícitos.

O que muda quando o GA4 vira uma ferramenta

O Model Context Protocol conecta um cliente como o OpenCode a um servidor que expõe operações estruturadas. O servidor oficial do Google Analytics usa a Admin API para descobrir contas, propriedades e configurações, e a Data API para executar relatórios.

Pelo navegador, a pergunta normalmente vira uma sequência de interações. Pelo MCP, ela pode virar uma sequência verificável:

1. Descobrir as contas e propriedades acessíveis.
2. Confirmar os detalhes da propriedade escolhida.
3. Definir intervalo, dimensões e métricas.
4. Executar o relatório.
5. Interpretar a resposta sem perder os parâmetros usados.

Isso traz quatro ganhos práticos:

• Repetição: a mesma pergunta pode ser feita com os mesmos critérios amanhã.
• Menos troca de contexto: não é preciso copiar dados do navegador para uma conversa ou planilha antes de analisá-los.
• Escopo explícito: propriedade, período, dimensões e métricas ficam visíveis no pedido.
• Composição: o resultado pode ser comparado com documentação, releases, campanhas ou outras fontes disponíveis ao agente.

O MCP não corrige instrumentação ausente, não concede acesso a propriedades e não elimina o atraso de processamento do GA4. Ele melhora a fronteira entre a pergunta e a API. Se o app não enviou page_view, o MCP não vai inventar esse evento. Se a conta não tem permissão na propriedade, o relatório continuará falhando.

Entenda a arquitetura antes de configurar

O projeto usado para o OAuth não é a propriedade do Analytics. Ele hospeda o cliente OAuth e as APIs habilitadas. A identidade autenticada é que determina quais contas e propriedades aparecem:

Conta Google autorizada
        |
        +-- Conta do Google Analytics
              +-- Propriedade do app
              +-- Propriedade do site
              +-- Outra propriedade compartilhada

Uma única autorização pode consultar todas as propriedades em que essa conta tenha permissão. Criar uma nova propriedade GA4 amanhã não exige criar outro MCP ou outro cliente OAuth. A propriedade nova só precisa estar acessível para a identidade já autorizada.

O servidor é local. O OpenCode inicia um processo Python na sua máquina, e esse processo usa o ADC (Application Default Credentials) para chamar o Google. O arquivo de configuração do OpenCode não precisa conter o refresh token, a chave secreta do cliente ou um ID de propriedade real.

Passo 1: instale um runner local

O repositório oficial publica o pacote analytics-mcp no PyPI e documenta o uso de pipx. Neste setup usei uvx, que executa o pacote em um ambiente isolado e aproveita o cache local:

uvx --from analytics-mcp analytics-mcp

Se você prefere seguir exatamente o caminho descrito no README do projeto, pode usar:

pipx run analytics-mcp

O importante é que o comando consiga iniciar um servidor MCP por stdin e stdout. Não é necessário clonar o repositório nem instalar o pacote dentro de cada projeto de código que será analisado.

O servidor é experimental. Isso significa que nomes de ferramentas e detalhes de configuração podem mudar. Fixar uma versão do pacote pode fazer sentido em uma equipe, mas o exemplo acima acompanha a versão atual do PyPI. Depois de uma atualização, repita a verificação de inicialização e a consulta de uma propriedade.

Passo 2: prepare o projeto do Google Cloud

Crie ou escolha um projeto Google Cloud dedicado ao cliente do OpenCode. O nome pode ser algo como mcp-google-analytics; ele não precisa ter o mesmo nome de nenhum app ou propriedade.

Ative estas APIs no projeto:

• Google Analytics Admin API
• Google Analytics Data API

Essas APIs pertencem ao projeto que faz as chamadas. Elas não adicionam esse projeto como administrador das propriedades GA4. As permissões continuam sendo as da conta Google autenticada no OAuth.

Passo 3: crie o cliente OAuth Desktop

Na configuração de clientes OAuth, configure a tela de consentimento e crie um cliente do tipo Desktop app.

Para um uso pessoal com um app externo em modo de teste:

1. Use um nome de aplicativo que identifique o cliente local.
2. Adicione a conta Google que realmente possui acesso ao Analytics como usuário de teste.
3. Baixe o JSON do cliente e mantenha o arquivo fora do repositório.
4. Não cole o conteúdo desse JSON no OpenCode, em issues ou em posts.

O escopo necessário para leitura de relatórios é:

https://www.googleapis.com/auth/analytics.readonly

O README do projeto mostra o comando gcloud auth application-default login com analytics.readonly e cloud-platform. O segundo escopo é usado pelo fluxo do gcloud para quota e autenticação de APIs Google, mas é mais amplo do que a leitura do Analytics. A tela de consentimento deixa isso claro: ele pode aparecer como acesso para ver, editar, configurar e excluir recursos do Google Cloud.

Essa diferença merece uma decisão consciente. Para uma configuração simples, siga o comando oficial e revise a permissão exibida antes de aprovar. Para uma política de menor privilégio, não aceite uma autorização mais ampla sem a aprovação da sua organização: use um fluxo OAuth aprovado pela sua equipe que produza ADC com o escopo de Analytics somente, ou peça ao administrador uma alternativa baseada em identidade de serviço. O MCP não precisa de permissão de administrador do GA4 para executar relatórios de leitura.

Com o caminho oficial do gcloud, o formato é:

gcloud auth application-default login \
  --client-id-file=<your-client-json-file> \
  --scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform

O comando grava as credenciais no local padrão do ADC. Se você usar outro arquivo, defina GOOGLE_APPLICATION_CREDENTIALS no ambiente que inicia o OpenCode. O refresh token é um segredo: proteja o arquivo com permissões restritas e nunca o versionar.

Uma armadilha específica do login remoto é colar no navegador a URL parcial exibida por --no-browser ou --remote-bootstrap. Essa URL ainda não contém todos os parâmetros de redirecionamento; aberta sozinha, ela pode retornar Missing required parameter: redirect_uri. O fluxo precisa ser executado pelo processo gcloud auxiliar ou por uma ferramenta OAuth que mantenha o estado e o redirect local.

Passo 4: adicione o servidor ao OpenCode

No opencode.json ou opencode.jsonc global, adicione uma entrada dentro de mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "google-analytics": {
      "type": "local",
      "command": ["uvx", "--from", "analytics-mcp", "analytics-mcp"],
      "enabled": true,
      "timeout": 60000,
    },
  },
}

Se uvx não estiver no PATH usado pelo OpenCode, substitua o primeiro item pelo caminho absoluto do executável. Preserve os outros servidores e campos existentes. O formato é importante: command é uma lista de argumentos, e cada servidor precisa declarar type: "local".

Não adicione GOOGLE_APPLICATION_CREDENTIALS só porque o README mostra essa variável para outro cliente. Quando o ADC está no local padrão, as bibliotecas Google o encontram automaticamente. Use environment apenas se a credencial estiver em um caminho alternativo:

"environment": {
  "GOOGLE_APPLICATION_CREDENTIALS": "{env:GOOGLE_APPLICATION_CREDENTIALS}"
}

Depois de salvar a configuração, encerre e reinicie o OpenCode. A configuração de MCP é carregada no início da sessão; editar o arquivo não reinicia um servidor já carregado.

Faça a primeira consulta na ordem certa

Comece pedindo descoberta, não um relatório. Uma instrução útil é:

Use o MCP do Google Analytics para listar minhas contas e propriedades acessíveis.
Mostre o nome de cada propriedade e seu property ID. Não adivinhe IDs.

Isso chama get_account_summaries. Em seguida, confirme a propriedade pelo nome e peça get_property_details para verificar fuso horário, moeda e tipo. O nome exibido é para humanos; o property_id é o identificador estável usado pelos relatórios.

Depois da seleção, faça um relatório estreito:

Use run_report na propriedade <your-property-id>.
Consulte os dois últimos dias de calendário disponíveis.
Dimensões: date e eventName.
Métricas: totalUsers, sessions e eventCount.
Ordene por data ascendente e eventCount descendente.
Mostre os parâmetros usados e uma tabela curta com os resultados.

Na validação desta instalação, uma consulta equivalente retornou uma sessão, um usuário, uma visualização de página e três eventos de uma propriedade de teste. A resposta também trouxe o fuso horário e a moeda configurados. Isso é uma prova melhor do que apenas ver o servidor listado no OpenCode: o processo iniciou, autenticou, localizou a propriedade e recebeu dados da Data API.

Use realtime e funis para perguntas diferentes

run_report é adequado para períodos históricos. Para quem está no site agora, peça run_realtime_report e deixe claro que a consulta deve usar dimensões e métricas de tempo real. Realtime não aceita o mesmo conjunto de dimensões do relatório histórico.

Para uma jornada, use run_funnel_report. Descreva os eventos em ordem e peça uma quebra por dispositivo, país ou outra dimensão disponível. Um funil de aquisição pode ser descrito assim:

Monte um funil na propriedade <your-property-id> com os passos:
1. session_start
2. page_view
3. sign_up
4. purchase
Mostre usuários em cada passo e a taxa de queda entre etapas.

Não peça ao agente para inventar uma dimensão customizada. Primeiro consulte get_custom_dimensions_and_metrics e use somente os nomes retornados para aquela propriedade. Uma dimensão cadastrada em outra propriedade não se torna válida automaticamente.

Limites que continuam existindo

O MCP não muda o comportamento do GA4. Há três limites que precisam aparecer em qualquer análise:

• Últimas 48 horas: a Data API trabalha normalmente com datas de calendário. Para uma janela exata de 48 horas, a borda por horário pode não estar disponível no relatório padrão.
• Atraso de ingestão: eventos recentes podem ainda não aparecer nos relatórios históricos. Realtime e relatórios padrão respondem a perguntas diferentes.
• Permissões: a conta do OAuth precisa ter acesso à propriedade. O projeto Cloud que hospeda o cliente não concede esse acesso.

Também não trate um número pequeno como um problema técnico automaticamente. Uma resposta com zero usuários pode ser tráfego zero, filtro incorreto, atraso de processamento ou propriedade errada. Peça ao agente para repetir a consulta sem filtro, confirmar a propriedade e mostrar os parâmetros antes de concluir que a instrumentação quebrou.

Armadilhas do uso pelo navegador e do uso via MCP

O navegador tem uma armadilha operacional: é fácil trocar de propriedade sem perceber, principalmente quando várias propriedades têm nomes semelhantes. O MCP reduz esse risco quando o fluxo começa por get_account_summaries, mas não o elimina se o prompt disser apenas “meu site”. Inclua o nome e confirme o ID.

O MCP tem uma armadilha diferente: deixar o agente escolher dimensões e métricas sem explicá-las. Uma pergunta como “o que aconteceu recentemente?” pode gerar uma resposta bonita, mas difícil de repetir. Diga o período, as dimensões, as métricas, a ordenação e o timezone que deve ser usado na apresentação.

A autenticação também merece separação. O OAuth define quem é a conta. O ADC define onde as bibliotecas encontram o token. O opencode.jsonc define como iniciar o servidor. Misturar os três em um único arquivo com segredos torna a configuração mais difícil de depurar e mais fácil de vazar.

Fluxo completo consolidado

Adaptando os placeholders para o seu ambiente, o processo fica assim:

# 1. Verifique o runner
uvx --from analytics-mcp analytics-mcp

# 2. Gere ADC pelo fluxo OAuth aprovado pela sua equipe
gcloud auth application-default login \
  --client-id-file=<your-client-json-file> \
  --scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform

# 3. Confirme que o projeto usado para APIs está configurado
gcloud config set project <your-cloud-project-id>

Depois, configure o bloco mcp.google-analytics, reinicie o OpenCode, liste as propriedades, confirme os detalhes e só então execute o primeiro run_report. Essa ordem reduz a chance de transformar um erro de autenticação, de propriedade ou de métrica em uma conclusão sobre os dados.

Checklist

• Crie um projeto Cloud dedicado ao cliente, sem confundi-lo com uma propriedade GA4.
• Ative a Admin API e a Data API.
• Crie um cliente OAuth Desktop e adicione a conta correta como usuário de teste quando necessário.
• Revise os escopos antes de aprovar o consentimento.
• Mantenha o ADC e o refresh token fora do repositório.
• Use uvx ou pipx para iniciar o pacote oficial.
• Configure o servidor como MCP local no OpenCode.
• Reinicie o OpenCode depois de editar a configuração.
• Comece por get_account_summaries e confirme o property_id.
• Declare dimensões, métricas, período e ordenação em cada relatório.
• Diferencie dados históricos de Realtime.
• Valide uma chamada real antes de considerar a instalação concluída.

O ganho do MCP não é substituir a interface do GA4. É tirar a consulta repetida do caminho de cliques e colocá-la em uma ferramenta que o agente pode chamar com parâmetros explícitos. O navegador continua sendo o melhor lugar para explorar visualmente; o MCP é melhor quando a pergunta precisa ser repetida, comparada e explicada sem recomeçar do zero.