VK Ads MCP

VK Ads MCP

VK Ads MCP conecta um aplicativo de IA ao painel de anúncios do VK Ads. Você pode perguntar quais campanhas estão gastando orçamento sem resultado, comparar grupos e anúncios, preparar uma nova campanha ou alterar um lance. Diferente de navegar manualmente pelas seções do painel, o assistente cruza campanhas, estatísticas, saldo e status em um único diálogo.

• 22 ferramentas. Campanhas, grupos, anúncios, estatísticas, saldo, limites de API, regiões, conexão do painel e consulta universal à API.
• Conexão pelo diálogo. Diga "conecte o VK Ads" — o servidor explicará onde obter client_id e client_secret, receberá o token e continuará renovando-o sozinho.
• Publicidade ao vivo. Lances, orçamentos e gastos são exibidos na moeda do painel de anúncios — sem conversão de micro-unidades.
• Hierarquia completa. Campanha (ad_plan) → grupo (ad_group) → anúncio (banner).
• Análise primeiro. Listas, relatórios, saldo e status são somente leitura.
• Alterações no painel real. Criação, atualização e ações de status são aplicadas imediatamente; o VK Ads não possui sandbox.

Comece com uma solicitação segura:

Mostre as campanhas da minha conta do VK Ads 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

Conteúdo

• Início rápido
• O que você pode delegar
• Como os objetos do VK Ads são estruturados
• O que pode alterar dados
• Conexão do painel
• Configuração
• Dados, limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

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

1. Adicione o servidor ao aplicativo de IA — instruções para cinco aplicativos abaixo.
2. Diga: "Conecte o VK Ads" — o servidor conduzirá a conexão diretamente no diálogo.
3. Pergunte: "Mostre as campanhas da minha conta do VK Ads e os gastos da semana passada por grupos de anúncios".

codex mcp add vk-ads -- npx -y mcp-vk-ads@latest

codex mcp list

claude mcp add \
  --transport stdio \
  --scope user \
  vk-ads \
  -- npx -y mcp-vk-ads@latest

claude mcp list

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

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

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

O que você pode delegar

Entender gastos e resultados

• "Mostre gastos, impressões, cliques e CTR por campanhas nos últimos 7 dias".
• "Quais anúncios estão gastando mais e não trazem resultado?"
• "Compare grupos de anúncios dentro desta campanha por gasto e cliques".

Entender por que a publicidade não está sendo exibida

• "Mostre status, entrega e moderação de todos os anúncios deste grupo".
• "Quais campanhas estão pausadas agora?"
• "Encontre anúncios que não passaram na moderação".

Preparar alterações na publicidade

• "Crie uma campanha de texto com orçamento diário de 5.000 rublos".
• "Altere o orçamento diário deste grupo para 1.500 rublos".
• "Pause o anúncio 12345".

Esses comandos alteram o painel real. Antes de executar, verifique se o assistente identificou corretamente a campanha, o grupo, o anúncio e o valor.

Encontrar dados para configuração

• "Mostre o saldo e a moeda do meu painel".
• "Quantas solicitações de API restam?"
• "Encontre o ID da região Moscou para segmentação".

Como os objetos do VK Ads são estruturados

O objeto tem três estados diferentes. status pode ser alterado: active, blocked ou deleted. delivery e moderation_status apenas explicam por que o objeto está sendo exibido ou não; não podem ser alterados diretamente.

O que pode alterar dados

As ferramentas tipadas de criação, atualização e mudança de status não possuem parâmetro interno confirmWrite. Como o aplicativo de IA solicita confirmação depende das configurações dele. Após erro de rede ou 5xx, não repita a criação às cegas: a operação pode ter sido aplicada; primeiro verifique a lista de objetos.

Conexão do painel

Diga ao assistente:

Conecte o VK Ads

Ele mostrará o que fazer: em ads.vk.com, abra Configurações → Acesso à API, crie um aplicativo e envie client_id e client_secret no chat. Em seguida, o servidor obterá o token e verificará em qual painel entrou. Não é necessário reiniciar o aplicativo de IA nem editar a configuração dele. Se a seção "Acesso à API" não estiver disponível, solicite acesso ao suporte do VK Ads.

Depois, a conexão se mantém sozinha: o token VK dura cerca de um dia e é renovado automaticamente via refresh_token. Para verificar o estado — "mostre o status da conexão"; para desconectar — "desconecte o VK Ads".

client_id e client_secret dão acesso total ao painel de anúncios, incluindo gasto de orçamento. O servidor os armazena em ~/.config/mcp-vk-ads/credentials.json com permissões somente do proprietário (0600) — client_secret é necessário porque o VK exige a cada renovação de token. Nenhuma ferramenta os retorna.

O VK Ads não possui fluxo de "entrar e confirmar" no navegador para servidores de terceiros: o cenário authorization_code do VK é fornecido apenas a parceiros com redirect_uri aprovado, portanto a conexão ocorre pelo aplicativo do próprio usuário. Painéis de clientes de agências exigem a concessão agency_client_credentials — para eles, é necessário um token pronto em VK_ADS_TOKEN (veja a documentação da API VK Ads).

Configuração

Não há nada para configurar: o servidor pergunta tudo no diálogo. As variáveis de ambiente são úteis apenas para CI e instalações automáticas, onde não há diálogo. Todas são opcionais — o servidor funciona sem nenhuma delas.

curl -X POST https://ads.vk.com/api/v2/oauth2/token.json \
  -d grant_type=client_credentials \
  -d client_id=ВАШ_CLIENT_ID \
  -d client_secret=ВАШ_CLIENT_SECRET

Dados, limites e trabalho em segundo plano

• Páginas e painéis grandes. Uma página de lista contém até 250 objetos. Quando autoPaginate, o servidor retorna no máximo 1.000 objetos e marca o resultado incompleto com o campo _truncated.
• Limites de API. A ferramenta get_throttling mostra o saldo atual dos limites. Verifique antes de operações em massa.
• Tentativas de solicitação. O timeout de uma solicitação é de 60 segundos. O servidor faz até três tentativas: para qualquer método quando 429, e para leitura também em erro de rede, timeout e 5xx. O atraso considera Retry-After e não excede 30 segundos.
• Sem monitoramento em segundo plano. O servidor funciona quando o aplicativo de IA o chama. Se o aplicativo suportar tarefas agendadas, você pode configurar solicitações periódicas de estatísticas ou status.
• Telemetria anônima. Por padrão, o servidor envia um identificador aleatório de instalação, nome do evento ou ferramenta, versões do servidor, Node.js, SO e cliente de IA. Não inclui token, dados do painel, argumentos de ferramentas, suas mensagens ou valores de variáveis de ambiente. Para desativá-la para servidores MCP do Ask Ads: ASKADS_TELEMETRY=0.

Documentação técnica

• Catálogo de recursos MCP — páginas por tarefas do usuário para cada ferramenta.
• Todas as ferramentas e parâmetros
• Documentação de desenvolvimento
• Pacote no npm
• Documentação da API VK Ads

Suporte

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