mcp-yandex-audience

Яндекс Аудитории MCP

A1 Яндекс Аудитории MCP conecta aplicativos de IA a segmentos, pixels e acessos do Yandex Audiences. Peça em linguagem natural para mostrar o que já existe na conta, preparar um segmento a partir de CRM, criar uma audiência semelhante ou conceder acesso a colegas — o assistente fará isso pela sua conta. A conexão começa diretamente no diálogo: não é necessário criar um token antecipadamente ou editar a configuração.

• 20 ferramentas. Segmentos, pixels, acessos, conexão de conta e chamada direta adicional à API.
• 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 segmentos imediatamente após a conexão.
• CRM e identificadores. CSV com e-mails e telefones, além de TSV/TXT com device ID, endereços MAC ou hashes SHA256.
• Dois passos para um segmento a partir de arquivo. Primeiro o upload, depois a confirmação separada dos parâmetros e o início do processamento.
• Sem instalação global. O pacote é executado via npx no Node.js 20+ e conecta-se ao cliente de IA via stdio.

Experimente com a primeira mensagem:

Mostre meus segmentos no Yandex Audiences: nomes, tipos e status atuais.

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

Veja o funcionamento em um minuto

Você: Conecte o Yandex Audiences.

Assistente: Fornece um link para entrar no Yandex. Abra-o com a conta à qual pertencem os segmentos desejados (ou à qual eles foram compartilhados), confirme o acesso e envie o código exibido.

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

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

Você: Carregue buyers.csv como segmento CRM "Compradores 2026" e pare após o upload.

Assistente: Faz o upload do arquivo — um segmento com status uploaded aparece na conta, mostra o id, o nome e os parâmetros, e aguarda uma confirmação separada. Após a confirmação, o processamento não é imediato, então o status é verificado pela lista de segmentos.

Conteúdo

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

Início rápido

São necessários Node.js 20 ou superior e uma conta no Yandex Audiences. O servidor é executado via npx, portanto não é necessário instalar o pacote separadamente. Não é preciso um token antecipadamente — a conexão ocorre diretamente no diálogo; para CI, é possível definir um token pronto, veja Conexão e configuração.

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 Audiences". O assistente conduzirá o login no Yandex e verificará o acesso aos segmentos.
3. Comece com uma solicitação segura, por exemplo: "Mostre meus segmentos no Yandex Audiences: nomes, tipos e status atuais".

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

codex mcp list

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

claude mcp list

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

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

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

O que pode ser solicitado

Verificar o que já existe na conta

• Visualizar segmentos, seus tipos, status e identificadores.
• Encontrar segmentos que ainda estão em processamento, terminaram com erro ou contêm dados insuficientes.
• Visualizar pixels, seus alcances em 7, 30 e 90 dias, além dos segmentos criados com base neles.
• Saber quem tem acesso a um segmento específico.

Preparar um segmento a partir de CRM

• Carregar CSV com as colunas email, phone, ext_id ou external_id.
• Carregar TSV/TXT com identificadores de dispositivos, endereços MAC ou hashes SHA256.
• Verificar os parâmetros do segmento carregado antes da confirmação.
• Salvar o segmento com o nome e o tipo de dados desejados e, em seguida, verificar o andamento do processamento.

Criar uma nova audiência

• Criar uma audiência semelhante com base em um segmento existente: da mais semelhante e restrita à mais ampla.
• Criar um segmento de visitantes por pixel em um período de 1 a 90 dias.
• Adicionar ao segmento de pixel condições por número de acionamentos e marcas UTM.

Trabalhar com pixels e acessos

• Criar ou renomear um pixel.
• Conceder a um colega ou agência acesso ao segmento: somente visualização ou edição.
• Revogar o acesso quando não for mais necessário.

Usar recursos adicionais da API

raw_request é necessário para operações que ainda não possuem uma ferramenta separada: por exemplo, reprocessamento de segmento ou restauração de pixel. É uma ferramenta para especialistas técnicos: ela pode executar gravação ou exclusão, portanto, para tarefas comuns, é melhor usar os comandos separados acima.

Parâmetros de entrada completos, respostas e status estão reunidos no referência de ferramentas.

Como funciona

O servidor trabalha com três entidades do Yandex Audiences:

Um segmento a partir de arquivo é criado em duas etapas:

1. Você envia um arquivo CSV, TSV ou TXT — o caminho para um arquivo local ou seu conteúdo, mas não ambas as fontes ao mesmo tempo. O servidor faz o upload do arquivo para o Yandex Audiences, e um objeto com status uploaded aparece na conta.
2. Com um comando separado, você confirma o nome, o tipo de dados e os parâmetros de processamento. Somente então o Yandex Audiences inicia o processamento.

A prontidão não aparece imediatamente: o servidor verifica o status pela lista de segmentos, onde são possíveis estados de processamento, erro ou volume insuficiente de dados. Para CRM, use CSV com cabeçalhos email, phone, ext_id ou external_id. Para dados com hash, a API aceita SHA256; MD5 não é suportado.

O servidor não gerencia campanhas publicitárias, lances e anúncios no Yandex Direct. O segmento pronto é conectado à campanha fora deste servidor MCP.

O que pode alterar dados

O Yandex Audiences é uma API com operações de gravação. O servidor MCP transmite ao cliente de IA informações sobre quais ferramentas leem, alteram ou excluem dados, mas as regras de confirmação são definidas pelo próprio aplicativo de IA.

O servidor não combina o upload do arquivo e a confirmação em uma única chamada oculta. Em caso de erro de rede ou resposta 5xx do servidor, ele não repete automaticamente operações de gravação: a operação pode já ter sido executada. Nessa situação, primeiro verifique o estado pela lista de segmentos, pixels ou acessos.

Conexão e configuração

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

1. No chat, peça para conectar o Yandex Audiences.
2. Abra o link do Yandex OAuth com a conta à qual pertencem os segmentos desejados (ou à qual eles foram compartilhados).
3. Confirme o acesso e envie o código ao assistente. Ele é de uso único, 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-audience/credentials.json com permissões somente do proprietário, e o acesso é renovado automaticamente. O servidor solicita duas permissões — leitura e alteração de segmentos do Audiences; campanhas, anúncios e outros serviços do Yandex não estão acessíveis a ele.

Para verificar o estado, peça "mostre o status da conexão com o Audiences"; para desconectar, "desconecte o Audiences". O acesso concedido ao aplicativo é revogado no Yandex ID.

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

1. Cadastre um aplicativo em oauth.yandex.ru/client/new.
2. Selecione as permissões do Yandex Audience: criação de segmentos e alteração de parâmetros dos seus segmentos e dos segmentos confiáveis e leitura de parâmetros dos seus segmentos e dos segmentos confiáveis.
3. Obtenha o token OAuth — para desenvolvimento, siga as instruções do token de depuração — e envie-o ao servidor em YANDEX_AUDIENCE_TOKEN.

O token está vinculado à conta Yandex: o servidor verá apenas os segmentos próprios e confiáveis do proprietário do token. Esse token é armazenado em texto simples na configuração do cliente de IA — trate-o como uma senha e não adicione a configuração com o token real ao Git. Mais detalhes na documentação oficial sobre autorização da API Yandex Audience.

Dados e telemetria

O servidor é executado na sua máquina e acessa api-audience.yandex.ru diretamente. O token OAuth é adicionado apenas às solicitações da Audience API — até mesmo raw_request aceita um caminho relativo, e o redirecionamento para um host externo é bloqueado. Ao entrar pelo diálogo, o servidor também acessa oauth.yandex.ru para trocar o código de confirmação e renovar o acesso; ao carregar via file_path, ele lê o arquivo local especificado e o envia ao Yandex Audience.

Por padrão, o servidor envia telemetria técnica anônima para usage.gistrec.cloud: inicialização do servidor (inclusive sem token configurado), nome da ferramenta chamada e código do motivo do problema de configuração — junto com um identificador aleatório de instalação, versão do pacote, nome e versão do cliente de IA, versão do Node.js e sistema operacional. O token OAuth, dados da conta, conteúdo de arquivos, argumentos de ferramentas e textos de consultas não são lidos nem enviados. O envio é feito em segundo plano com timeout de 2 segundos e não afeta o funcionamento do servidor; a implementação está em src/telemetry.ts.

Para desativar a telemetria, defina a variável de ambiente:

ASKADS_TELEMETRY=0

Limitações

• O processamento não é imediato. Após confirmar um segmento, verifique o status dele pela lista de segmentos: podem ocorrer status de processamento, erros e volume de dados insuficiente.
• A exclusão de um segmento é irreversível. Para pixels, a API prevê recuperação por um método separado, disponível via raw_request.
• Não é possível consultar um único segmento separadamente. A API retorna uma lista geral — o servidor localiza o segmento desejado pelo id nela.
• Mínimo de 100 registros e máximo de 1 GB. Ao confirmar um segmento menor, você pode enviar check_size: false, mas esse segmento não pode ser usado no Direct até que o tamanho aumente.
• Cotas da API. Até 30 solicitações por segundo por IP e 5.000 solicitações por dia por login. Criação e alteração de segmentos: até 10 por minuto, 100 por hora e 500 por dia. Solicitações com erro também consomem cota.
• Em caso de limitação temporária da API. O servidor repete a solicitação com atraso até o número de tentativas definido em YANDEX_AUDIENCE_MAX_RETRIES; a resposta 429 não significa que você precisa criar o objeto novamente.
• Sem monitoramento em segundo plano. O servidor funciona apenas durante a chamada do aplicativo de IA e não aguarda a conclusão do processamento. Se o seu aplicativo suportar tarefas agendadas, configure verificações periódicas de status pela lista de segmentos.

Documentação técnica

• Catálogo de recursos MCP — páginas com tarefas de usuário para cada ferramenta.
• Todas as ferramentas — dados de entrada, respostas, status e limitações.
• Desenvolvimento — execução local, testes, build e verificação smoke read-only.
• Publicação — lançamento do pacote npm e listagem nos catálogos MCP.
• Pacote npm — versão publicada do mcp-yandex-audience.
• API Yandex Audience — documentação oficial.

Suporte

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