Google Analytics

Acesse dados do Google Analytics 4 (GA4) usando o Model Context Protocol.

GitHub
70
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

Verified on MseeP

Servidor MCP do Google Analytics

smithery badge

Uma implementação de servidor MCP para acessar dados do Google Analytics 4 (GA4), construída usando o SDK TypeScript do Model Context Protocol.

Recursos

  • Obter métricas de visualizações de página com dimensões personalizáveis
  • Acompanhar usuários ativos e novos ao longo do tempo
  • Analisar eventos específicos e suas métricas
  • Monitorar métricas de comportamento do usuário (duração da sessão, taxa de rejeição)
  • Seleção flexível de intervalo de datas para todas as consultas

Pré-requisitos

  • Node.js 20 ou superior
  • Uma propriedade do Google Analytics 4.
  • Um projeto do Google Cloud com a API de Dados do Analytics habilitada.
  • Uma conta de serviço com credenciais para acessar a API.

Configuração

Para usar este servidor, você precisa configurar a autenticação com o Google Analytics. Isso é feito usando uma conta de serviço.

1. Habilitar a API de Dados do Google Analytics

  1. Acesse o Console do Google Cloud.
  2. Selecione o projeto que deseja usar.
  3. No menu de navegação, vá para APIs e Serviços > Biblioteca.
  4. Pesquise por "Google Analytics Data API" e habilite-a.

2. Criar uma Conta de Serviço

  1. No Console do Google Cloud, navegue até IAM e Administrador > Contas de Serviço.
  2. Clique em "Criar Conta de Serviço".
  3. Dê um nome à conta de serviço (por exemplo, "GA4 MCP Server").
  4. Clique em "Criar e Continuar".
  5. Você pode pular a concessão de acesso da conta de serviço ao projeto.
  6. Clique em "Concluído".
  7. Encontre a conta de serviço que você acabou de criar e clique nos três pontos em "Ações".
  8. Selecione "Gerenciar chaves" e depois "Adicionar Chave" > "Criar nova chave".
  9. Escolha JSON como o tipo de chave e clique em "Criar". Um arquivo JSON com as credenciais será baixado.

3. Conceder Acesso da Conta de Serviço ao Google Analytics

  1. Abra o Google Analytics.
  2. Navegue até a seção Administrador da sua propriedade GA4.
  3. Na coluna Propriedade, clique em Gerenciamento de Acesso à Propriedade.
  4. Clique no botão "+" para adicionar um novo usuário.
  5. No campo "Endereço de e-mail", cole o client_email do arquivo de credenciais JSON que você baixou.
  6. Atribua o papel de "Visualizador". Você não precisa notificar o usuário.
  7. Clique em "Adicionar".

4. Definir Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

  • GOOGLE_CLIENT_EMAIL: O client_email do arquivo JSON da sua conta de serviço.
  • GOOGLE_PRIVATE_KEY: O private_key do arquivo JSON da sua conta de serviço.
  • GA_PROPERTY_ID: O ID da sua propriedade do Google Analytics 4.

Você pode defini-las no seu ambiente ou usar um arquivo .env.

export GOOGLE_CLIENT_EMAIL="your-service-account@your-project.iam.gserviceaccount.com"
export GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n"
export GA_PROPERTY_ID="your_property_id"

Instalação

Instalando via Smithery

Para instalar o Google Analytics Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install mcp-server-google-analytics --client claude

Instalação Manual

npm install -g mcp-server-google-analytics

Ou use diretamente com npx:

npx mcp-server-google-analytics

Uso

Iniciando o Servidor

pnpm start

Configuração no Claude Desktop

Adicione isso à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-analytics"],
      "env": {
        "GOOGLE_CLIENT_EMAIL": "your-service-account@project.iam.gserviceaccount.com",
        "GOOGLE_PRIVATE_KEY": "your-private-key",
        "GA_PROPERTY_ID": "your-ga4-property-id"
      }
    }
  }
}

Funções Disponíveis

runReport

Execute um relatório flexível para obter dados de análise.

Entrada:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "dimensions": [{ "name": "country" }, { "name": "city" }],
  "metrics": [{ "name": "activeUsers" }, { "name": "newUsers" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "country",
      "stringFilter": {
        "value": "United States"
      }
    }
  }
}

getPageViews

Obtenha métricas de visualizações de página para um intervalo de datas específico:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "dimensions": ["page", "country"] // Optional
}

getActiveUsers

Obtenha métricas de usuários ativos:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
}

getEvents

Obtenha métricas de eventos:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "eventName": "purchase" // Optional
}

getUserBehavior

Obtenha métricas de comportamento do usuário:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
}

Considerações de Segurança

  • Menor Privilégio: Conceda apenas o papel de "Visualizador" à conta de serviço no Google Analytics.
  • Gerenciamento de Chaves: Mantenha o arquivo de chave da sua conta de serviço seguro e não o exponha em código do lado do cliente.
  • Variáveis de Ambiente: Use variáveis de ambiente para armazenar informações sensíveis, como o e-mail do cliente, a chave privada e o ID da propriedade.

Contribuindo

Contribuições são bem-vindas! Leia nosso Guia de Contribuição para detalhes sobre nosso código de conduta e o processo para enviar pull requests.

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.