O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Teste o servidor MCP do Google Analytics

O servidor do Protocolo de Contexto de Modelo (MCP) do Google Analytics permite conectar seus dados do Google Analytics a modelos de linguagem grandes (LLMs) e agentes de IA, como o Gemini. Você pode usar o servidor MCP para consultar relatórios em linguagem natural, inspecionar configurações de propriedades e criar agentes de análise personalizados.

Configurar o servidor MCP Ver no GitHub Assistir o tutorial de configuração

Pré-requisitos

Antes de configurar o servidor MCP do Google Analytics, conclua os seguintes requisitos:

Instale o Python e um executor de pacotes:
- Instale o Python 3.10 ou uma versão mais recente.
- Instale o pipx ou o uv (uvx) para executar o servidor MCP em um ambiente Python isolado.
Ative as APIs do Google Analytics em :
- Crie ou selecione um projeto do .
- Ative a API Admin do Google Analytics (analyticsadmin.googleapis.com) e a API Google Analytics Data (analyticsdata.googleapis.com) no seu projeto:
```
gcloud services enable analyticsadmin.googleapis.com \
  analyticsdata.googleapis.com \
  --project=YOUR_PROJECT_ID
```
Conceder acesso à propriedade do Google Analytics:
- Na interface do Google Analytics, conceda à sua conta de usuário ou de serviço pelo menos o papel de Leitor (roles/analytics.viewer) na propriedade do Google Analytics de destino. Para instruções, consulte Gerenciar o acesso e a restrição de dados.

Configurar a autenticação

O servidor MCP do Google Analytics faz a autenticação usando o Application Default Credentials (ADC) com o escopo OAuth 2.0 somente leitura do Google Analytics:

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

É possível configurar o ADC usando sua conta de usuário do Google ou uma conta de serviço.

Opção 1: autenticar com credenciais de usuário

Instale e inicialize a CLI gcloud.

Execute gcloud auth application-default login com os escopos necessários:

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

Se você usar um arquivo de configuração de cliente OAuth 2.0 para computador ou Web baixado (consulte Gerenciar clientes OAuth), transmita --client-id-file:

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

Quando o comando for concluído, copie o caminho das credenciais impresso no console (Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]). Você vai usar esse caminho em GOOGLE_APPLICATION_CREDENTIALS ao configurar o cliente MCP.

Opção 2: autenticar com uma conta de serviço

Para autenticar com uma conta de serviço que tenha acesso de visualização à sua propriedade do Google Analytics:

Arquivo de chave JSON da conta de serviço:defina GOOGLE_APPLICATION_CREDENTIALS na configuração do cliente MCP como o caminho absoluto do arquivo JSON da sua conta de serviço.

Identidade temporária de conta de serviço:gere credenciais do ADC assumindo a identidade temporária da conta de serviço com a CLI gcloud:

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

Configurar o cliente MCP

O servidor é publicado no PyPI como analytics-mcp e expõe os scripts de console analytics-mcp e google-analytics-mcp.

Nas configurações a seguir, substitua:

PATH_TO_CREDENTIALS_JSON pelo caminho absoluto para o arquivo JSON do ADC ou da conta de serviço.
YOUR_PROJECT_ID pelo ID do projeto do em que você ativou as APIs do Google Analytics.

CLI e IDE do Antigravity

Instale a CLI do Antigravity ou o IDE do Antigravity.

Adicione o servidor analytics-mcp a ~/.gemini/config/mcp_config.json (ou .agents/mcp_config.json no seu espaço de trabalho):

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

Verifique se o analytics-mcp está conectado:
- CLI do Antigravity:execute agy e digite /mcp para ver os servidores MCP configurados.
- IDE do Antigravity:abra Configurações > Personalizações > Servidores MCP instalados e clique em Atualizar.

Claude Desktop e Claude Code

Para o Claude Desktop, adicione o servidor ao arquivo claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json no macOS ou %APPDATA%\Claude\claude_desktop_config.json no Windows):

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

Para o Claude Code, registre o servidor usando a ferramenta de linha de comando:

claude mcp add analytics-mcp \
  --scope user \
  -e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" \
  -e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \
  -- pipx run analytics-mcp

Cursor

Adicione o servidor a .cursor/mcp.json no diretório do projeto (ou ~/.cursor/mcp.json para configuração global). É possível invocar google-analytics-mcp usando uvx ou pipx:

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "uvx",
      "args": ["--from", "analytics-mcp", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Para executar a versão de desenvolvimento mais recente diretamente do GitHub usando uvx, atualize "args":

"args": [
  "--from",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

Como alternativa, para usar pipx, mude "command" para "pipx" e defina "args" como:

"command": "pipx",
"args": [
  "run",
  "--spec",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

Ferramentas do MCP disponíveis

O servidor MCP do Google Analytics usa a API Admin e a API Data v1 para expor ferramentas somente leitura ao seu cliente MCP:

Descoberta de contas e propriedades (API Admin):
- get_account_summaries: lista as contas e propriedades do Google Analytics acessíveis ao usuário autenticado (accountSummaries.list).
- get_property_details: retorna detalhes de configuração de uma propriedade específica do Google Analytics (properties.get).
- list_google_ads_links: lista as vinculações a contas do Google Ads de uma propriedade (properties.googleAdsLinks.list).
- list_property_annotations: lista as anotações configuradas para uma propriedade (properties.reportingDataAnnotations.list).
Relatórios e inspeção de esquema (API Data v1):
- get_custom_dimensions_and_metrics: recupera dimensões e métricas personalizadas definidas para uma propriedade (getMetadata).
- run_report: executa um relatório padrão do Google Analytics (runReport).
- run_realtime_report: executa um relatório de tempo real do Google Analytics (runRealtimeReport).
- run_funnel_report: gera um relatório de análise detalhada de funil do Google Analytics (runFunnelReport).
- run_conversions_report: executa um relatório de performance de conversões (runConversionsReport).

Comandos de amostra

Depois de conectar, faça perguntas ao assistente de IA, como:

Quantos usuários acessaram meu site ontem?
Quais foram meus produtos mais vendidos ontem?
Tenho um orçamento de marketing de US $5.000/mês e preciso gerar mais receita. Me ajude a criar um plano de marketing baseado em dados.
Quais dimensões e métricas personalizadas estão configuradas na minha propriedade?
Quais são os eventos mais acessados na minha propriedade do Google Analytics nos últimos 90 dias?

Solução de problemas

Use a lista de verificação a seguir para resolver erros comuns de configuração e de tempo de execução:

403 PERMISSION_DENIED (API não ativada ou permissões de propriedade insuficientes):
- Confirme se a API Admin do Google Analytics (analyticsadmin.googleapis.com) e a API Google Analytics Data (analyticsdata.googleapis.com) estão ativadas no projeto do especificado por GOOGLE_CLOUD_PROJECT.
- Verifique se o usuário ou a conta de serviço de autenticação tem pelo menos o papel de Leitor (roles/analytics.viewer) na propriedade de destino do Google Analytics na interface do Google Analytics.
- Se o estado de erro indicar Request had insufficient authentication scopes, execute novamente gcloud auth application-default login com os escopos https://www.googleapis.com/auth/analytics.readonly e https://www.googleapis.com/auth/cloud-platform.
Projeto de cota ausente (GOOGLE_CLOUD_PROJECT) ou 403 ACCESS_NOT_CONFIGURED:
- As solicitações autenticadas com credenciais do ADC do usuário exigem um projeto de cota do com as APIs do Google Analytics ativadas. Defina "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID" na configuração env do servidor MCP ou defina o projeto de cota no arquivo ADC:
```
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
```
401 UNAUTHENTICATED ou arquivo de credenciais não encontrado:
- Use um caminho absoluto para GOOGLE_APPLICATION_CREDENTIALS (por exemplo, /Users/username/.config/gcloud/application_default_credentials.json). Evite variáveis ~ ou $HOME, já que muitos hosts MCP não expandem variáveis de shell dentro de arquivos de configuração JSON.
- Execute gcloud auth application-default login novamente se as credenciais de usuário tiverem expirado.
Falha ao iniciar o servidor (erros de versão do spawn pipx ENOENT, uvx: command not found ou Python):
- Confirme se o Python 3.10 ou uma versão mais recente está instalado (python3 --version).
- Os aplicativos de GUI para computador (como o Claude Desktop e o Cursor) geralmente não herdam o PATH do shell interativo. Substitua "pipx" ou "uvx" em "command" pelo caminho binário absoluto retornado por which pipx ou which uvx (por exemplo, /opt/homebrew/bin/pipx ou /Users/username/.local/bin/pipx).