Yandex Direct MCP

Yandex Direct MCP

Yandex Direct MCP conecta um aplicativo de IA à conta de publicidade do Yandex Direct. Pergunte em linguagem natural para onde está indo o orçamento de publicidade, compare campanhas, anúncios e frases-chave e, em seguida, prepare ou faça as alterações necessárias sem alternar entre as seções da conta. A conexão começa diretamente no diálogo: não é necessário criar um token antecipadamente ou editar a configuração.

• 44 ferramentas. Campanhas, grupos, anúncios, frases-chave, lances, ajustes, extensões, estatísticas, saldo, diretórios e conexão de conta diretamente no diálogo.
• Duas formas de conexão. O servidor remoto por URL não exige obter token manualmente e apenas lê dados; o local via npx dá acesso total à conta.
• Conexão no chat. O Yandex abrirá a página de login; após o código do chat, você pode trabalhar com a publicidade imediatamente, e o acesso é renovado automaticamente.
• Dinheiro de forma clara. Nas ferramentas convenientes, orçamentos, lances e saldo são exibidos na moeda da conta, não em microunidades da API.
• Publicidade real. Alterações locais são aplicadas na conta de produção e podem afetar os gastos. Para trabalhar em ambiente de teste, existe a sandbox do Yandex Direct.

Experimente com a primeira mensagem:

Mostre as campanhas da minha conta e os gastos da semana passada por grupos de anúncios.

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

Veja o funcionamento em um minuto

Você: Conecte o Yandex Direct.

Assistente: Fornece um link para entrar no Yandex. Abra-o com a conta que tem acesso à conta de publicidade desejada, confirme o acesso e envie o código exibido.

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

Assistente: Conecta o Direct e mostra a conta. Não é necessário reiniciar o aplicativo.

Você: Mostre as campanhas da minha conta e os gastos da semana passada por grupos de anúncios.

Assistente: Encontra as campanhas, gera um relatório por grupos de anúncios e mostra os gastos na moeda da conta.

Conteúdo

• Início rápido
• O que você pode delegar
• 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

1. Escolha a forma de conexão e adicione o servidor ao aplicativo de IA conforme as instruções abaixo.
2. Abra um novo diálogo e pergunte: «Mostre as campanhas da minha conta e os gastos da semana passada por grupos de anúncios».

Análise sem obter token manualmente — por URL

O servidor remoto https://mcp.askads.ru/mcp conecta-se por meio de um aplicativo que suporta MCP por URL. Entre no Yandex no navegador e confirme o acesso: não é necessário passar o token na configuração. Esta opção é somente leitura — estatísticas, auditoria e visualização de objetos; ela não altera as configurações de publicidade.

No Claude Code, você pode adicioná-lo com o comando:

claude mcp add --transport http yandex-direct https://mcp.askads.ru/mcp

Após conectar, abra /mcp e faça a autorização. Nos demais aplicativos que suportam HTTP MCP, adicione a mesma URL pela interface do aplicativo.

Acesso total — localmente via npx

Para criar e alterar objetos, é necessário Node.js 20+. O npx baixa o servidor na primeira execução — não é necessário instalar o pacote separadamente. Não é preciso obter token antecipadamente — a conexão começa diretamente no diálogo:

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 Direct» — o assistente guiará você pelo login no Yandex e mostrará a conta.

Para CI e instalações de agentes — token pronto e YANDEX_DIRECT_LOGIN, veja Conexão e configuração.

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

codex mcp list

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

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

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

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

O que você pode delegar

Verificar como o orçamento está sendo gasto

• «Quais campanhas gastaram mais na semana passada?»
• «Quais anúncios recebem impressões e cliques, mas não geram conversões?»
• «Compare gastos, CTR e preço médio do clique por campanhas no mês».
• «Mostre o saldo da conta e o restante da cota diária da API».

Encontrar pontos de melhoria

• «Quais frases-chave gastam orçamento, mas não geram cliques?»
• «Quais grupos e anúncios estão pausados ou não passaram na moderação?»
• «Verifique quais ajustes de lance estão ativos para dispositivos móveis».
• «Quais links rápidos e esclarecimentos esta campanha possui?»

Preparar alterações

• «Sugira novos lances para frases com CTR alto e mostre as alterações antes de aplicar».
• «Verifique se a campanha tem palavras negativas para este tema e prepare uma lista».
• «Monte os parâmetros de uma nova campanha de texto para Moscou: orçamento, grupos, frases-chave e anúncios».

Executar uma ação explícita

• «Adicione estas frases-chave ao grupo 123 e defina o lance de 45 ₽».
• «Pause o anúncio 456».
• «Envie a página com imagem para a biblioteca de anúncios».

Como funciona

A publicidade geralmente é estruturada em três níveis: campanha → grupo de anúncios → anúncio. No grupo estão as frases-chave, as configurações de exibição e os ajustes de lance. Os anúncios podem ter links rápidos, esclarecimentos, cartões de visita e imagens.

O servidor ajuda a visualizar esses objetos em conjunto: relacionar o gasto da campanha com as estatísticas dos grupos, frases-chave e anúncios. Ele sabe criar novas campanhas e anúncios apenas do tipo texto. Campanhas de outros tipos podem ser lidas, renomeadas, ter o orçamento alterado, pausadas, arquivadas e excluídas por identificador.

As estatísticas não são geradas instantaneamente: get_statistics inicia o relatório no serviço Reports e aguarda sua conclusão. Listas grandes autoPaginate percorre as páginas de resultados automaticamente.

O que pode alterar dados

O servidor remoto por URL apenas lê dados. O servidor local via npx pode alterar a conta de publicidade ativa:

As ferramentas enviam ao aplicativo de IA rótulos de leitura, escrita e ação potencialmente irreversível. O aplicativo pode exibir uma confirmação, mas o comportamento depende do cliente. A solicitação direta à API não executará gravação adicional sem confirmWrite=true; para alterar a publicidade, é necessária uma solicitação explícita.

Conexão e configuração

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

1. No chat, peça para conectar o Yandex Direct.
2. Abra o link do Yandex OAuth com a conta que tem acesso à conta de publicidade desejada.
3. Confirme o acesso e envie no chat o código exibido. Pronto, você já pode trabalhar com a publicidade: não é necessário reiniciar o cliente nem editar a configuração.

A conexão continua funcionando sozinha: o acesso é renovado automaticamente e não expira após um ano. Para verificar o status, peça «mostre o status da conexão»; para desconectar, «desconecte o Direct». O acesso concedido pode ser revogado no Yandex ID.

Para CI e instalações automáticas, onde não há diálogo, a configuração por variáveis de ambiente está disponível:

Obter um token pronto para YANDEX_DIRECT_TOKEN é possível pelo link, entrando com a conta que tem acesso à conta desejada:

Obter token do Yandex Direct

Não publique o token em chats, repositórios e capturas de tela: ele dá acesso à conta de publicidade, incluindo ações que podem afetar o orçamento.

Dados e telemetria

Por padrão, o servidor envia eventos técnicos anônimos: identificador aleatório de instalação, nome da ferramenta chamada, versões do servidor, do aplicativo de IA, do Node.js e do sistema operacional. Isso é necessário para entender quais partes do servidor são usadas e se há problemas na inicialização. O token do Yandex, os dados da conta de publicidade, os argumentos das ferramentas, os textos das solicitações, os valores e os nomes das variáveis de ambiente não são enviados.

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

ASKADS_TELEMETRY=0

Limitações

• Cota diária da API. Cada chamada consome Units. A ferramenta get_quota mostra quanto foi gasto, quanto resta e o que está disponível hoje.
• Limites de relatórios. Os relatórios do Yandex têm suas próprias restrições de volume e quantidade por dia, e é preciso aguardar a prontidão do relatório no serviço Reports.
• Listas grandes. Se o limite interno for atingido durante a paginação automática, o servidor marca explicitamente o resultado como incompleto, em vez de ocultar isso.
• Erros temporários. O servidor faz até três tentativas em caso de limitações de frequência. Erros de rede e de servidor são repetidos automaticamente apenas para leitura, para não duplicar uma alteração.
• Conta de produção. As alterações locais são aplicadas na conta de anúncios real e podem afetar os gastos. Para testes, use a sandbox (YANDEX_DIRECT_SANDBOX=true).
• Sem monitoramento contínuo. O servidor funciona durante a chamada do aplicativo de IA. Se o aplicativo suportar tarefas agendadas, é possível configurar uma consulta periódica para verificar as métricas desejadas.

Documentação técnica

• Catálogo de recursos MCP — páginas sobre tarefas de usuário para cada ferramenta.
• Todas as ferramentas — parâmetros, respostas e limites de cada ferramenta.
• Desenvolvimento — estrutura do projeto e trabalho com o código-fonte.
• API Яндекс Директа — fonte primária sobre a API e suas limitações.
• Pacote npm — versões publicadas do servidor.

Suporte

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