Yandex Metrica MCP

Yandex Metrica MCP

Yandex Metrica MCP conecta um aplicativo de IA à análise web do seu site. Pergunte em linguagem natural de onde vêm os visitantes, como a conversão está mudando ou onde a taxa de rejeição está crescendo — o assistente buscará os dados do seu contador e explicará o resultado. A conexão começa diretamente no diálogo: não é necessário criar um token antecipadamente ou editar a configuração.

• Oito ferramentas. Contadores, metas e relatórios da Metrica, conexão e desconexão de acesso, além de uma consulta universal à API.
• Relatórios e conversões. Visitas, usuários, visualizações, rejeições, duração da visita, fontes, dispositivos e metas no período selecionado.
• Conexão no chat. O Yandex abrirá a página de login; o código de uso único é válido por 10 minutos, e o servidor verificará o acesso aos contadores imediatamente após a conexão.
• Consultas comuns — somente leitura. As ferramentas especializadas não alteram contadores, metas ou dados da Metrica.
• Sem corte silencioso. No relatório, os valores totais e o indicador de amostragem ficam visíveis; em resultados grandes, o servidor sinaliza se atingiu o limite.

Experimente com a primeira mensagem:

Quantas visitas, usuários e rejeições meu site teve na última semana?

Conectar servidor · Ver cenários · Abrir documentação técnica

Veja o funcionamento em um minuto

Você: Conecte o Yandex Metrica.

Assistente: Fornece um link para entrar no Yandex. Abra-o com a conta que tem acesso aos contadores desejados, confirme o acesso e envie o código exibido.

Você: Envia o código da página do Yandex.

Assistente: Conecta a Metrica, verifica se os contadores estão visíveis e informa o resultado. Não é necessário reiniciar o aplicativo.

Você: Nos últimos 30 dias, mostre as fontes de tráfego e a conversão da meta "Finalização do pedido".

Assistente: Encontra a meta, gera o relatório por fontes e mostra visitas, conclusões da meta e conversão. Se a Metrica aplicou amostragem, sinaliza que os números são aproximados.

Conteúdo

• Início rápido
• O que você pode solicitar
• Como funciona
• O que pode alterar os dados
• Conexão e configuração
• Dados e telemetria
• Limitações
• Documentação técnica
• Suporte

Início rápido

É necessário Node.js 20 ou superior. O servidor é executado via npx, portanto não é preciso instalar o pacote separadamente.

1. Adicione o servidor ao aplicativo de IA — abaixo há um exemplo aberto para Codex; os demais aplicativos estão reunidos em instruções recolhíveis.
2. Escreva: "Conecte o Yandex Metrica". O assistente conduzirá o login no Yandex e verificará imediatamente se os seus contadores estão visíveis.
3. Faça a primeira pergunta, por exemplo: "Quais fontes geraram mais visitas no último mês?"

codex mcp add yandex-metrica -- npx -y mcp-yandex-metrica@latest

codex mcp list

claude mcp add --transport stdio --scope user yandex-metrica -- npx -y mcp-yandex-metrica@latest

claude mcp list

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-metrica@latest"]
    }
  }
}

{
  "mcpServers": {
    "yandex-metrica": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-metrica@latest"]
    }
  }
}

{
  "servers": {
    "yandex-metrica": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-metrica@latest"]
    }
  }
}

O que você pode solicitar

Entender o que está acontecendo com o site

• "Quantas visitas, usuários e visualizações houve na última semana?"
• "Mostre a dinâmica de visitas por dia em junho."
• "Em quais dispositivos a taxa de rejeição é maior?"

Encontrar a fonte de tráfego e avaliar sua qualidade

• "Mostre as fontes de tráfego do mês e ordene por visitas."
• "Compare busca orgânica e anúncios por usuários e rejeições."
• "Quais fontes geraram mais transições nesta semana?"

Analisar conversões

• "Quais metas estão configuradas no contador?"
• "Qual é a conversão da meta 'Finalização do pedido' nos últimos 30 dias?"
• "Mostre as fontes que trouxeram mais conclusões de meta."

Verificar acesso e precisão dos dados

• "Quais contadores estão disponíveis para mim?"
• "Mostre o status da conexão com a Metrica."
• "Os dados deste relatório são precisos ou a Metrica usou amostragem?"

Como funciona

O servidor trabalha com três entidades familiares:

Normalmente, o assistente primeiro encontra um contador disponível, depois — se necessário — uma meta, e só então gera o relatório. Na resposta da Metrica, há o total de todas as linhas, o tamanho da saída e o indicador de amostragem.

O que pode alterar os dados

O servidor marca qualquer escrita arbitrária como uma ação potencialmente destrutiva. A forma como o aplicativo de IA solicita confirmação depende do próprio aplicativo; antes dessa solicitação, verifique o caminho, o método e os dados.

Conexão e configuração

Para uso comum, não é necessário um token antecipadamente:

1. No chat, peça para conectar o Yandex Metrica.
2. Abra o link do Yandex OAuth com a conta que tem acesso aos contadores desejados.
3. Confirme o acesso e envie o código ao assistente. Ele é válido por 10 minutos e é trocado por um token apenas dentro do servidor em execução.

O servidor usa PKCE: o código do chat não pode ser trocado por um token por conta própria. O token obtido é armazenado localmente em ~/.config/mcp-yandex-metrica/credentials.json com permissões somente para o proprietário. Com um refresh-token salvo, o acesso é renovado automaticamente.

Para CI e instalações não padronizadas, a configuração está disponível por variáveis de ambiente:

Se você usar seu próprio aplicativo OAuth, solicite nele a permissão "Obtenção de estatísticas, leitura de parâmetros dos seus contadores e dos confiáveis" (metrika:read).

Dados e telemetria

Por padrão, o servidor envia telemetria técnica anônima: identificador aleatório da instalação, nome do evento ou ferramenta, versão do servidor, versão do Node.js, sistema operacional e informações sobre o cliente de IA conectado. Não incluem token, dados dos contadores, argumentos das ferramentas, suas mensagens ou valores de variáveis de ambiente.

Para desativar a telemetria dos servidores MCP da Ask Ads, defina a variável de ambiente:

ASKADS_TELEMETRY=0

Limitações

• Amostragem da Metrica. Em períodos longos ou relatórios complexos, a API pode retornar dados aproximados. Consulte os campos sampled e sample_share; para um cálculo mais preciso, reduza o período ou use accuracy: "full".
• Tamanho do relatório. Uma consulta retorna até 10.000 linhas. A paginação automática para em no máximo 100 páginas, 100.000 linhas ou aproximadamente 1 MB de dados e marca a resposta incompleta com o campo _truncated.
• Tentativas de consulta. O tempo limite de uma consulta é de 60 segundos. O servidor faz até três tentativas em erro temporário: GET — em erro de rede, 429 e 5xx; POST e DELETE — somente com 429, para não repetir uma ação de alteração. O atraso considera Retry-After e não excede 30 segundos.
• Dados reais. A Metrica não tem sandbox. As ferramentas especializadas leem dados, mas POST e DELETE por consulta arbitrária alteram objetos reais.
• Sem monitoramento em segundo plano. O servidor funciona quando o aplicativo de IA o chama e não monitora métricas por conta própria. Se o aplicativo suportar tarefas agendadas, você pode configurar uma solicitação periódica de relatório nele.

Documentação técnica

• Catálogo de recursos MCP — páginas por tarefas do usuário para cada ferramenta.
• Todas as ferramentas — parâmetros, respostas e limites de cada ferramenta.
• Documentação de desenvolvimento — estrutura do projeto e uso da demonstração.
• Pacote no npm.
• API do Yandex Metrica.

Suporte

Encontrou um erro ou falta um cenário? Crie uma issue ou escreva no Telegram.