VK Ads MCP

VK Ads MCP

VK Ads MCP conecta una aplicación de IA al panel publicitario de VK Ads. Puedes preguntar qué campañas gastan presupuesto sin resultados, comparar grupos y anuncios, preparar una nueva campaña o cambiar una oferta. A diferencia de navegar manualmente por las secciones del panel, el asistente relaciona campañas, estadísticas, saldo y estados en un solo diálogo.

• 22 herramientas. Campañas, grupos, anuncios, estadísticas, saldo, límites de API, regiones, conexión del panel y consulta universal a la API.
• Conexión desde el diálogo. Di «conecta VK Ads» — el servidor explicará dónde obtener client_id y client_secret, recibirá el token y luego lo renovará automáticamente.
• Publicidad en vivo. Ofertas, presupuestos y gastos se muestran en la moneda del panel publicitario, sin convertir microunidades.
• Jerarquía completa. Campaña (ad_plan) → grupo (ad_group) → anuncio (banner).
• Primero el análisis. Listas, informes, saldo y estados están disponibles solo en modo lectura.
• Los cambios se aplican en el panel real. La creación, actualización y acciones sobre estados se aplican de inmediato; VK Ads no tiene entorno de pruebas.

Comienza con una consulta segura:

Muestra las campañas de mi cuenta de VK Ads y el gasto de la semana pasada por grupos de anuncios.

Conectar servidor · Ver escenarios · Abrir documentación técnica

Ver el funcionamiento en un minuto

Contenido

• Inicio rápido
• Qué se puede encargar
• Cómo están organizados los objetos de VK Ads
• Qué puede modificar los datos
• Conexión del panel
• Configuración
• Datos, límites y trabajo en segundo plano
• Documentación técnica
• Soporte

Inicio rápido

Se necesita Node.js 20 o superior. El servidor se ejecuta mediante npx, por lo que no es necesario instalar el paquete por separado; no se requiere token durante la instalación.

1. Añade el servidor a la aplicación de IA — instrucciones para cinco aplicaciones abajo.
2. Di: «Conecta VK Ads» — el servidor guiará la conexión directamente en el diálogo.
3. Pregunta: «Muestra las campañas de mi cuenta de VK Ads y el gasto de la semana pasada por grupos de anuncios».

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"]
    }
  }
}

Qué se puede encargar

Analizar el gasto y los resultados

• «Muestra el gasto, las impresiones, los clics y el CTR por campañas de los últimos 7 días».
• «¿Qué anuncios gastan más y no aportan resultados?»
• «Compara los grupos de anuncios dentro de esta campaña por gasto y clics».

Entender por qué la publicidad no se muestra

• «Muestra el estado, la entrega y la moderación de todos los anuncios de este grupo».
• «¿Qué campañas están pausadas ahora?»
• «Encuentra anuncios que no pasaron la moderación».

Preparar cambios en la publicidad

• «Crea una campaña de texto con un presupuesto diario de 5 000 rublos».
• «Cambia el presupuesto diario de este grupo a 1 500 rublos».
• «Pausa el anuncio 12345».

Estos comandos modifican el panel real. Antes de ejecutarlos, asegúrate de que el asistente haya identificado correctamente la campaña, el grupo, el anuncio y el importe.

Encontrar datos para la configuración

• «Muestra el saldo y la moneda de mi panel».
• «¿Cuántas solicitudes a la API quedan?»
• «Encuentra el ID de la región Moscú para la segmentación».

Cómo están organizados los objetos de VK Ads

Un objeto tiene tres estados diferentes. status se puede cambiar: active, blocked o deleted. delivery y moderation_status solo explican por qué el objeto se muestra o no; no se pueden modificar directamente.

Qué puede modificar los datos

Las herramientas tipadas de creación, actualización y cambio de estado no tienen un parámetro interno confirmWrite. La forma en que la aplicación de IA solicita confirmación depende de su configuración. Tras un error de red o 5xx, no repitas la creación a ciegas: la operación podría haberse aplicado; primero verifica la lista de objetos.

Conexión del panel

Dile al asistente:

Conecta VK Ads

Te mostrará qué hacer: en ads.vk.com abre Configuración → Acceso a API, crea una aplicación y envía al chat client_id y client_secret. Luego el servidor obtendrá el token y verificará a qué panel accedió. No es necesario reiniciar la aplicación de IA ni editar su configuración. Si la sección «Acceso a API» no está disponible, solicita acceso al soporte de VK Ads.

La conexión se mantiene sola: el token de VK dura aproximadamente un día y se renueva automáticamente mediante refresh_token. Para verificar el estado — «muestra el estado de la conexión», para desconectar — «desconecta VK Ads».

client_id y client_secret otorgan acceso completo al panel publicitario, incluido el gasto de presupuesto. El servidor los almacena en ~/.config/mcp-vk-ads/credentials.json con permisos solo para el propietario (0600) — client_secret es necesario porque VK lo exige en cada renovación del token. Ninguna herramienta los devuelve.

VK Ads no ofrece un flujo de «iniciar sesión y confirmar» en el navegador para servidores de terceros: el escenario authorization_code de VK solo se otorga a socios con redirect_uri acordado, por lo que la conexión se realiza a través de la aplicación del propio usuario. Los paneles de clientes de agencias requieren una concesión agency_client_credentials — para ellos se necesita un token listo en VK_ADS_TOKEN (consulta la documentación de VK Ads API).

Configuración

No hay nada que configurar: el servidor solicita todo lo necesario en el diálogo. Las variables de entorno solo son útiles para CI e instalaciones automáticas donde no hay diálogo. Todas son opcionales: el servidor funciona sin ninguna de ellas.

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

Datos, límites y trabajo en segundo plano

• Páginas y paneles grandes. Una página de lista contiene hasta 250 objetos. Con autoPaginate, el servidor devuelve como máximo 1 000 objetos y marca el resultado incompleto con el campo _truncated.
• Límites de API. La herramienta get_throttling muestra el saldo actual de límites. Verifícalo antes de operaciones masivas.
• Reintentos de solicitudes. El tiempo de espera de una solicitud es de 60 segundos. El servidor realiza hasta tres reintentos: para cualquier método con 429, y para lectura también ante error de red, tiempo de espera y 5xx. La demora tiene en cuenta Retry-After y no supera los 30 segundos.
• Sin supervisión en segundo plano. El servidor funciona cuando la aplicación de IA lo invoca. Si la aplicación admite tareas programadas, puedes configurar solicitudes periódicas de estadísticas o estados.
• Telemetría anónima. Por defecto, el servidor envía un identificador de instalación aleatorio, el nombre del evento o herramienta, las versiones del servidor, Node.js, el sistema operativo y el cliente de IA. No incluye token, datos del panel, argumentos de herramientas, tus mensajes ni valores de variables de entorno. Para desactivarla en los servidores MCP de Ask Ads: ASKADS_TELEMETRY=0.

Documentación técnica

• Catálogo de capacidades MCP — páginas por tareas de usuario para cada herramienta.
• Todas las herramientas y parámetros
• Documentación de desarrollo
• Paquete en npm
• Documentación de VK Ads API

Soporte

¿Encontraste un error o falta un escenario? Crea un issue o escribe a Telegram.