Google Analytics MCP: uma ferramenta de servidor local para conectar dados GA4 a grandes modelos

O MCP (Model Context Protocol) do Google Analytics é uma ferramenta de código aberto que permite aos usuários conectar os dados do Google Analytics 4 (GA4) com grandes modelos (por exemplo, Claude, Cursor etc.) por meio de um servidor local. Ela fornece recursos de consulta e gerenciamento de dados por meio da API de administração e da API de dados do Google Analytics. Os usuários podem executar o servidor localmente e analisar dados como o tráfego do site e o comportamento do usuário com a ajuda do processamento de linguagem natural. O projeto está hospedado no GitHub, é mantido pela equipe do Google Analytics e oferece suporte ao ambiente Python, adequado para desenvolvedores e analistas de dados. O código é atualizado com frequência, com a última atualização em julho de 2025, e a comunidade é altamente ativa.

Lista de funções

• Obtenha informações sobre a conta e a propriedade do Google Analytics.
• Consulta detalhes de propriedades específicas, como configuração e definições.
• Listar links para contas do Google Ads.
• Execute relatórios de dados GA4 com suporte para dimensões e métricas personalizadas.
• Obtenha as principais dimensões de relatório para um atributo específico, incluindo dimensões personalizadas.
• Obtenha as principais métricas de relatórios para atributos específicos, incluindo métricas personalizadas.
• Fornece uma lista de dimensões e indicadores padrão para facilitar a análise de dados.
• Suporte para consultas em linguagem natural, combinado com modelos grandes para lidar com requisitos de dados complexos.

Usando a Ajuda

Processo de instalação

Para usar o Google Analytics MCP, os usuários precisam instalar e configurar o servidor em seu ambiente local. Veja a seguir as etapas detalhadas de instalação e uso:

1. Preparação do ambiente
   • Certifique-se de que o Python 3.10 ou posterior esteja instalado em seu sistema. Execute o seguinte comando para verificar a versão:

     python --version
     python3 --version
     

   • montagempipE verifique a versão:

     pip --version
     pip3 --version
     

2. armazém de clones
   Clone o repositório do Google Analytics MCP localmente usando o Git:

   git clone https://github.com/googleanalytics/google-analytics-mcp.git
   cd google-analytics-mcp
   

3. Criação de um ambiente virtual
   Para evitar conflitos de dependência, é recomendável criar um ambiente virtual Python:

   python3 -m venv venv
   source venv/bin/activate  # Linux/Mac
   venv\Scripts\activate     # Windows
   

4. Instalação de dependências
   Instale as dependências necessárias para o projeto no ambiente virtual:

   pip install -r requirements.txt
   

5. Configuração das credenciais do Google Analytics
   • Crie uma conta de serviço no Google Cloud Console para ativar a API de dados do Google Analytics.
   • Faça o download do arquivo de chave JSON para a conta de serviço, anotando o caminho como/path/to/your/service-account-key.json.
   • Definição de variáveis de ambienteGOOGLE_APPLICATION_CREDENTIALS::

     export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"  # Linux/Mac
     set GOOGLE_APPLICATION_CREDENTIALS="path\to\your\service-account-key.json"     # Windows
     

   • Opcional: Editar~/.gemini/settings.jsonAdicione o caminho das credenciais:

     {
     "mcpServers": {
     "analytics-mcp": {
     "command": "pipx",
     "args": ["run", "--spec", "git+https://github.com/googleanalytics/google-analytics-mcp.git", "google-analytics-mcp"],
     "env": {
     "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json"
     }
     }
     }
     }
     

6. Servidor de operações
   Use o seguinte comando para iniciar o servidor MCP:

   pipx run --spec git+https://github.com/googleanalytics/google-analytics-mcp.git google-analytics-mcp
   

   ou executados em um ambiente virtual:

   python -m ga4_mcp_server
   

7. conexão de teste
   Execute o código a seguir para verificar as credenciais do GA4:

   import os
   from google.analytics.data_v1beta import BetaAnalyticsDataClient
   os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/service-account-key.json"
   client = BetaAnalyticsDataClient()
   print("✅ GA4 credentials working!")
   

   Se você vir a mensagem "✅ GA4 credentials working!", a configuração foi bem-sucedida.

Funções principais

1. Obter informações sobre a conta e a propriedade
   fazer uso deget_account_summariesA ferramenta consulta a conta do Google Analytics do usuário e a lista de atributos. Depois de executá-la, o servidor retorna o ID da conta, o ID do atributo e outras informações, o que é adequado para uma visão geral rápida da estrutura da conta.
2. Relatórios de dados operacionais
   fazer uso derun_reportA ferramenta gera relatórios GA4. O usuário precisa especificar o ID do atributo, o intervalo de datas, a dimensão e as métricas. Por exemplo, consultar o país/região e os dados de usuários ativos dos últimos 7 dias:

   {
   "propertyId": "properties/123456789",
   "dateRanges": [{"startDate": "7daysAgo", "endDate": "yesterday"}],
   "dimensions": [{"name": "country"}],
   "metrics": [{"name": "activeUsers"}]
   }
   

   Os resultados do relatório são retornados no formato JSON, contendo dados para as dimensões e indicadores especificados.

3. Acesso a dimensões e indicadores
   • fazer uso deget_dimensionsresponder cantandoget_metricsObtenha as principais dimensões e métricas de um atributo, incluindo dimensões e métricas personalizadas.
   • fazer uso deget_standard_dimensionsresponder cantandoget_standard_metricsObtenha uma lista de dimensões e métricas padrão para o GA4, adequada para relatórios de configuração inicial.
4. consulta em linguagem natural
   O MCP oferece suporte ao uso de linguagem natural para consultar dados por meio de modelos grandes, como o Claude. Por exemplo, digite "Compare a duração média da sessão por categoria de dispositivo nos últimos 30 dias":
   • O servidor converte a solicitação em uma chamada de API, gerando um relatório.
   • Os resultados de retorno são apresentados em formato de tabela ou JSON para facilitar a compreensão.

Operação da função em destaque

1. Integração com modelos grandes
   O servidor MCP é executado localmente e permite que os usuários combinem dados do GA4 com modelos grandes. Por exemplo, usando o Claude ou o Cursor, insira um comando de linguagem natural, como "Mostrar exibições de página por navegador nos últimos 90 dias". O servidor analisa o comando, chama a API do GA4 e retorna dados estruturados.
2. Gerenciamento de links do Google Ads
   fazer uso delist_google_ads_linksConsulta links para contas do Google Ads com atributos GA4. Os resultados retornados incluem o ID da conta e o status do link, adequados para que os profissionais de marketing otimizem seus posicionamentos de anúncios.
3. Dimensões e indicadores personalizados
   Os usuários podem acessar oget_dimensionsresponder cantandoget_metricsObtenha dimensões e métricas personalizadas para criar relatórios personalizados. Por exemplo, analise o número de acionadores de um evento específico (por exemplo, um evento de "compra").

advertência

• Certifique-se de que a conta de serviço tenha permissões para a API de dados e a API de administração do Google Analytics.
• Verifique a conexão com a Internet; o servidor precisa ter acesso à API do Google.
• Atualize regularmente o código do repositório para obter os recursos mais recentes:

  git pull origin main
  

cenário do aplicativo

1. Análise de tráfego do site
   Os webmasters usam o MCP para consultar os dados do GA4 e analisar as fontes de tráfego, o comportamento do usuário e as conversões nos últimos 30 dias para ajudar a otimizar o conteúdo do site e as estratégias de marketing.
2. Avaliação da eficácia da publicidade
   A equipe de marketing trabalha comlist_google_ads_linksresponder cantandorun_reportFunções para comparar as taxas de cliques e de conversão de diferentes campanhas de anúncios e ajustar o orçamento de posicionamento.
3. Otimização de produtos orientada por dados
   Os gerentes de produtos usam consultas de linguagem natural para analisar o tempo de permanência do usuário e as taxas de rejeição em páginas específicas para otimizar a experiência do usuário.
4. Teste de integração do desenvolvedor
   O desenvolvedor integra o servidor MCP à ferramenta de análise de dados, testando chamadas de API e retornos de dados para garantir a estabilidade da operação do sistema.

QA

1. Como faço para proteger minhas credenciais do GA4?
   Armazene os arquivos de chave da conta de serviço em um local seguro para evitar o compartilhamento público. Use variáveis de ambiente ou~/.gemini/settings.jsonConfigure as credenciais para evitar vazamentos.
2. Quais modelos grandes são compatíveis com a MCP?
   Suporte para clientes MCP, como Claude, Cursor, Gemini CLI, etc., com a possibilidade de expansão para modelos mais compatíveis no futuro.
3. O que devo fazer se minha consulta de relatório falhar?
   Verifique as permissões da conta de serviço, o status de ativação da API e a conectividade da rede. Certifique-se de quepropertyIdCorreto, o formato do intervalo de datas é "AAAA-MM-DD" ou "7diasAgo".
4. Como posso visualizar as dimensões e métricas suportadas?
   fazer uso deget_standard_dimensionsresponder cantandoget_standard_metricsObter uma lista de critérios, ouget_dimensionsresponder cantandoget_metricsObtenha dimensões e métricas personalizadas específicas de atributos.