Yandex Direct MCP

Yandex Direct MCP

Yandex Direct MCP conecta una aplicación de IA a la cuenta publicitaria de Yandex Direct. Pregunta en lenguaje natural a dónde va el presupuesto publicitario, compara campañas, anuncios y frases clave, y luego prepara o aplica los cambios necesarios sin cambiar entre secciones de la cuenta. La conexión comienza directamente en el diálogo: no es necesario crear un token de antemano ni editar la configuración.

• 44 herramientas. Campañas, grupos, anuncios, frases clave, pujas, ajustes, extensiones, estadísticas, saldo, directorios y conexión de la cuenta directamente en el diálogo.
• Dos formas de conexión. El servidor remoto por URL no requiere obtener un token manualmente y solo lee datos; el local a través de npx da acceso completo a la cuenta.
• Conexión en el chat. Yandex abrirá la página de inicio de sesión; después del código del chat puedes trabajar con la publicidad de inmediato, y el acceso se renueva automáticamente.
• Dinero en formato claro. En las herramientas convenientes, los presupuestos, pujas y saldo se muestran en la moneda de la cuenta, no en microunidades de la API.
• Publicidad real. Los cambios locales se aplican en la cuenta de producción y pueden afectar el gasto. Para trabajar en un entorno de prueba, existe el sandbox de Yandex Direct.

Prueba con el primer mensaje:

Muestra las campañas de mi cuenta 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

Tú: Conecta Yandex Direct.

Asistente: Proporciona un enlace para iniciar sesión en Yandex. Ábrelo con la cuenta que tenga acceso a la cuenta publicitaria deseada, confirma el acceso y envía el código mostrado.

Tú: Envía el código de la página de Yandex.

Asistente: Conecta Direct y muestra la cuenta. No es necesario reiniciar la aplicación.

Tú: Muestra las campañas de mi cuenta y el gasto de la semana pasada por grupos de anuncios.

Asistente: Encuentra las campañas, genera un informe por grupos de anuncios y muestra el gasto en la moneda de la cuenta.

Contenido

• Inicio rápido
• Qué se puede delegar
• Cómo funciona
• Qué puede modificar datos
• Conexión y configuración
• Datos y telemetría
• Limitaciones
• Documentación técnica
• Soporte

Inicio rápido

1. Elige el método de conexión y añade el servidor a la aplicación de IA según las instrucciones a continuación.
2. Abre un nuevo diálogo y pregunta: «Muestra las campañas de mi cuenta y el gasto de la semana pasada por grupos de anuncios».

Análisis sin obtener token manualmente — por URL

El servidor remoto https://mcp.askads.ru/mcp se conecta a través de una aplicación que admite MCP por URL. Inicia sesión en Yandex en el navegador y confirma el acceso: no es necesario pasar el token en la configuración. Esta opción es solo de lectura — estadísticas, auditoría y visualización de objetos; no modifica la configuración de la publicidad.

En Claude Code puedes añadirlo con el comando:

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

Después de conectarte, abre /mcp y completa la autorización. En otras aplicaciones que admiten HTTP MCP, añade la misma URL a través de la interfaz de la aplicación.

Acceso completo — localmente a través de npx

Para crear y modificar objetos se necesita Node.js 20+. npx descargará el servidor en el primer inicio — no es necesario instalar el paquete por separado. No se requiere obtener un token de antemano — la conexión comienza directamente en el diálogo:

1. Añade el servidor a la aplicación de IA — a continuación se muestra un ejemplo para Codex; las demás aplicaciones están recopiladas en instrucciones plegables.
2. Escribe: «Conecta Yandex Direct» — el asistente te guiará a través del inicio de sesión en Yandex y mostrará la cuenta.

Para instalaciones de CI y agentes — token listo y YANDEX_DIRECT_LOGIN, consulta Conexión y configuración.

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

Qué se puede delegar

Verificar cómo se gasta el presupuesto

• «¿Qué campañas gastaron más la semana pasada?»
• «¿Qué anuncios reciben impresiones y clics, pero no generan conversiones?»
• «Compara el gasto, el CTR y el precio medio por clic de las campañas del mes».
• «Muestra el saldo de la cuenta y el resto de la cuota diaria de la API».

Encontrar puntos de mejora

• «¿Qué frases clave gastan presupuesto pero no generan clics?»
• «¿Qué grupos y anuncios están actualmente pausados o no pasan la moderación?»
• «Comprueba qué ajustes de pujas están activos para dispositivos móviles».
• «¿Qué enlaces rápidos y aclaraciones tiene esta campaña?»

Preparar cambios

• «Propón nuevas pujas para frases con CTR alto y muestra los cambios antes de aplicarlos».
• «Comprueba si la campaña tiene palabras negativas para este tema y prepara una lista».
• «Recopila los parámetros de una nueva campaña de texto para Moscú: presupuesto, grupos, frases clave y anuncios».

Ejecutar una acción explícita

• «Añade estas frases clave al grupo 123 y establece una puja de 45 ₽».
• «Pausa el anuncio 456».
• «Envía la página con la imagen a la biblioteca de anuncios».

Cómo funciona

La publicidad generalmente se estructura en tres niveles: campaña → grupo de anuncios → anuncio. En el grupo se encuentran las frases clave, la configuración de impresiones y los ajustes de pujas. Los anuncios pueden tener enlaces rápidos, aclaraciones, tarjetas de visita e imágenes.

El servidor ayuda a ver estos objetos en conjunto: relacionar el gasto de la campaña con las estadísticas de los grupos, las frases clave y los anuncios. Puede crear nuevas campañas y anuncios solo de tipo texto. Las campañas de otros tipos se pueden leer, renombrar, cambiar su presupuesto, pausar, archivar y eliminar por identificador.

Las estadísticas no se generan al instante: get_statistics inicia un informe en el servicio Reports y espera a que esté listo. Las listas grandes autoPaginate recorren las páginas de resultados automáticamente.

Qué puede modificar datos

El servidor remoto por URL solo lee datos. El servidor local a través de npx puede modificar la cuenta publicitaria en producción:

Las herramientas transmiten a la aplicación de IA etiquetas de lectura, escritura y acción potencialmente irreversible. La aplicación puede mostrar una confirmación, pero su comportamiento depende del cliente. La solicitud directa a la API no realizará una escritura adicional sin confirmWrite=true; para modificar la publicidad se necesita una solicitud explícita.

Conexión y configuración

Para el uso habitual no se necesita un token de antemano:

1. En el chat, pide conectar Yandex Direct.
2. Abre el enlace de Yandex OAuth con la cuenta que tenga acceso a la cuenta publicitaria deseada.
3. Confirma el acceso y envía el código mostrado en el chat. Eso es todo, ya puedes trabajar con la publicidad: no es necesario reiniciar el cliente ni editar la configuración.

La conexión se mantiene sola: el acceso se renueva automáticamente y no caduca al año. Para verificar el estado, pide «muestra el estado de la conexión»; para desconectar, «desconecta Direct». El acceso otorgado se revoca en Yandex ID.

Para CI e instalaciones automáticas donde no hay diálogo, está disponible la configuración mediante variables de entorno:

Puedes obtener un token listo para YANDEX_DIRECT_TOKEN a través del enlace, iniciando sesión con la cuenta que tenga acceso a la cuenta deseada:

Obtener token de Yandex Direct

No publiques el token en chats, repositorios ni capturas de pantalla: da acceso a la cuenta publicitaria, incluidas acciones que pueden afectar el presupuesto.

Datos y telemetría

Por defecto, el servidor envía eventos técnicos anónimos: un identificador aleatorio de instalación, el nombre de la herramienta invocada, las versiones del servidor, la aplicación de IA, Node.js y el sistema operativo. Esto es necesario para entender qué partes del servidor se utilizan y si surgen problemas al iniciar. El token de Yandex, los datos de la cuenta publicitaria, los argumentos de las herramientas, los textos de las solicitudes, los valores y nombres de las variables de entorno no se envían.

Para desactivar la telemetría para los servidores MCP de Ask Ads, establece la variable de entorno:

ASKADS_TELEMETRY=0

Limitaciones

• Cuota diaria de la API. Cada llamada consume Units. La herramienta get_quota muestra cuánto se ha gastado, cuánto queda y cuánto está disponible hoy.
• Límites de informes. Los informes de Yandex tienen sus propias restricciones de volumen y cantidad por día, y hay que esperar a que el informe esté listo en el servicio Reports.
• Listas grandes. Si se alcanza el límite interno durante la paginación automática, el servidor marca explícitamente el resultado como incompleto, en lugar de ocultarlo.
• Errores temporales. El servidor realiza hasta tres reintentos ante limitaciones de frecuencia. Los errores de red y de servidor se reintentan automáticamente solo para operaciones de lectura, para no duplicar un cambio.
• Cuenta real. Los cambios locales se aplican en la cuenta publicitaria real y pueden afectar el gasto. Para pruebas, use el sandbox (YANDEX_DIRECT_SANDBOX=true).
• Sin monitoreo continuo. El servidor funciona durante la llamada desde la aplicación de IA. Si la aplicación admite tareas programadas, puede configurar una solicitud periódica para verificar las métricas necesarias.

Documentación técnica

• Catálogo de capacidades MCP — páginas por tareas de usuario para cada herramienta.
• Todas las herramientas — parámetros, respuestas y límites de cada herramienta.
• Desarrollo — estructura del proyecto y trabajo con el código fuente.
• API de Yandex Direct — fuente original de la API y sus limitaciones.
• Paquete npm — versiones publicadas del servidor.

Soporte

¿Encontró un error o falta un escenario? Cree un issue o escriba a Telegram.