mcp-yandex-audience

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

A1 Яндекс Аудитории MCP conecta una aplicación de IA con segmentos, píxeles y accesos de Yandex Audiences. Pide en lenguaje natural que te muestre lo que ya hay en la cuenta, que prepare un segmento desde CRM, que cree una audiencia similar o que otorgue acceso a colegas: el asistente lo hará a través de tu cuenta. La conexión comienza directamente en el diálogo: no necesitas crear un token de antemano ni editar la configuración.

• 20 herramientas. Segmentos, píxeles, accesos, conexión de cuenta y una llamada API directa adicional.
• Conexión en el chat. Yandex abrirá la página de inicio de sesión; el código de un solo uso es válido durante 10 minutos, y el servidor verificará el acceso a los segmentos inmediatamente después de la conexión.
• CRM e identificadores. CSV con correos electrónicos y teléfonos, así como TSV/TXT con device ID, direcciones MAC o hashes SHA256.
• Dos pasos para un segmento desde archivo. Primero la carga, luego una confirmación separada de los parámetros y el inicio del procesamiento.
• Sin instalación global. El paquete se ejecuta mediante npx en Node.js 20+ y se conecta al cliente de IA a través de stdio.

Prueba con este primer mensaje:

Muéstrame mis segmentos en Yandex Audiences: nombres, tipos y estados actuales.

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

Ver cómo funciona en un minuto

Tú: Conecta Yandex Audiences.

Asistente: Te da un enlace para iniciar sesión en Yandex. Ábrelo con la cuenta a la que pertenecen los segmentos que necesitas (o a la que se le hayan confiado), confirma el acceso y envía el código que se muestra.

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

Asistente: Conecta Audiences, verifica si los segmentos son visibles y te informa del resultado. No es necesario reiniciar la aplicación.

Tú: Carga buyers.csv como segmento CRM «Compradores 2026» y detente después de la carga.

Asistente: Carga el archivo: en la cuenta aparece un segmento con estado uploaded, muestra su id, nombre y parámetros, y espera una confirmación separada. Después de la confirmación, el procesamiento no es inmediato, por lo que el estado se verifica a través de la lista de segmentos.

Contenido

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

Inicio rápido

Se necesitan Node.js 20 o superior y una cuenta de Yandex Audiences. El servidor se ejecuta mediante npx, por lo que no es necesario instalar el paquete por separado. No se necesita un token de antemano: la conexión se realiza directamente en el diálogo; para CI se puede configurar un token listo, ver Conexión y configuración.

1. Añade el servidor a la aplicación de IA: abajo se muestra un ejemplo para Codex; las demás aplicaciones están recopiladas en instrucciones plegables.
2. Escribe: «Conecta Yandex Audiences». El asistente te guiará a través del inicio de sesión en Yandex y verificará el acceso a los segmentos.
3. Comienza con una solicitud segura, por ejemplo: «Muéstrame mis segmentos en Yandex Audiences: nombres, tipos y estados actuales».

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

Qué se puede encargar

Verificar qué hay ya en la cuenta

• Ver segmentos, sus tipos, estados e identificadores.
• Encontrar segmentos que aún se están procesando, que terminaron con error o que contienen datos insuficientes.
• Ver píxeles, sus alcances de 7, 30 y 90 días, así como los segmentos creados a partir de ellos.
• Saber a quién se le ha otorgado acceso a un segmento específico.

Preparar un segmento desde CRM

• Cargar CSV con las columnas email, phone, ext_id o external_id.
• Cargar TSV/TXT con identificadores de dispositivos, direcciones MAC o hashes SHA256.
• Verificar los parámetros del segmento cargado antes de confirmarlo.
• Guardar el segmento con el nombre y tipo de datos deseados, y luego verificar el progreso del procesamiento.

Crear una nueva audiencia

• Crear una audiencia similar basada en un segmento existente: desde una más parecida y reducida hasta una más amplia.
• Crear un segmento de visitantes mediante píxel para un período de 1 a 90 días.
• Añadir al segmento de píxel condiciones sobre el número de activaciones y etiquetas UTM.

Trabajar con píxeles y accesos

• Crear o renombrar un píxel.
• Otorgar a un colega o agencia acceso a un segmento: solo lectura o edición.
• Revocar el acceso cuando ya no sea necesario.

Usar capacidades adicionales de la API

raw_request es necesario para operaciones que aún no tienen una herramienta separada: por ejemplo, reprocesar un segmento o restaurar un píxel. Es una herramienta para especialistas técnicos: puede realizar escrituras o eliminaciones, por lo que para tareas habituales es mejor usar los comandos específicos anteriores.

Los parámetros de entrada completos, las respuestas y los estados están recopilados en la referencia de herramientas.

Cómo funciona

El servidor trabaja con tres entidades de Yandex Audiences:

Un segmento desde archivo se crea en dos pasos:

1. Tú envías un archivo CSV, TSV o TXT: la ruta a un archivo local o su contenido, pero no ambas fuentes a la vez. El servidor carga el archivo en Yandex Audiences y en la cuenta aparece un objeto con estado uploaded.
2. Con un comando separado confirmas el nombre, el tipo de datos y los parámetros de procesamiento. Solo después de esto, Yandex Audiences comienza el procesamiento.

La disponibilidad no aparece de inmediato: el servidor verifica el estado a través de la lista de segmentos, donde son posibles estados de procesamiento, error o volumen de datos insuficiente. Para CRM usa CSV con encabezados email, phone, ext_id o external_id. Para datos con hash, la API acepta SHA256; MD5 no es compatible.

El servidor no gestiona campañas publicitarias, pujas ni anuncios en Yandex Direct. El segmento listo se conecta a la campaña fuera de este servidor MCP.

Qué puede modificar los datos

Yandex Audiences es una API con operaciones de escritura. El servidor MCP transmite al cliente de IA información sobre qué herramientas leen, modifican o eliminan datos, pero las reglas de confirmación las define la propia aplicación de IA.

El servidor no combina la carga del archivo y la confirmación en una sola llamada oculta. Ante un error de red o una respuesta 5xx del servidor, no repite automáticamente las operaciones de escritura: la operación podría ya haberse ejecutado. En esa situación, primero verifica el estado a través de la lista de segmentos, píxeles o accesos.

Conexión y configuración

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

1. En el chat, pide conectar Yandex Audiences.
2. Abre el enlace de Yandex OAuth con la cuenta a la que pertenecen los segmentos que necesitas (o a la que se le hayan confiado).
3. Confirma el acceso y envía el código al asistente. Es de un solo uso, válido durante 10 minutos y se intercambia por un token solo dentro del servidor en ejecución.

El servidor usa PKCE: el código del chat por sí solo no se puede intercambiar por un token. El token obtenido se almacena localmente en ~/.config/mcp-yandex-audience/credentials.json con permisos solo para el propietario, y el acceso se renueva automáticamente. El servidor solicita dos permisos: lectura y modificación de segmentos de Audiences; las campañas, los anuncios y el resto de servicios de Yandex no le son accesibles.

Para verificar el estado, pide «muestra el estado de la conexión con Audiences»; para desconectar, «desconecta Audiences». El acceso otorgado a la aplicación se revoca en Yandex ID.

Para CI e instalaciones no estándar, la configuración está disponible mediante variables de entorno:

1. Registra una aplicación en oauth.yandex.ru/client/new.
2. Selecciona los permisos de Yandex Audiences: creación de segmentos y modificación de parámetros de segmentos propios y de confianza y lectura de parámetros de segmentos propios y de confianza.
3. Obtén un token OAuth — para desarrollo, sigue las instrucciones del token de depuración — y pásalo al servidor en YANDEX_AUDIENCE_TOKEN.

El token está vinculado a la cuenta de Yandex: el servidor solo verá los segmentos propios y de confianza del propietario del token. Este token se almacena en texto plano en la configuración del cliente de IA — trátalo como una contraseña y no agregues la configuración con un token real a Git. Más detalles en la documentación oficial sobre autorización de la API de Yandex Audiences.

Datos y telemetría

El servidor se ejecuta en tu máquina y accede a api-audience.yandex.ru directamente. El token OAuth solo se agrega a las solicitudes de Audience API — incluso raw_request acepta una ruta relativa, y el acceso a un host externo está bloqueado. Al iniciar sesión desde el diálogo, el servidor también consulta oauth.yandex.ru para intercambiar el código de confirmación y renovar el acceso; al cargar a través de file_path, lee el archivo local especificado y lo envía a Yandex Audiences.

Por defecto, el servidor envía a usage.gistrec.cloud telemetría técnica anónima: inicio del servidor (incluso sin token configurado), nombre de la herramienta invocada y código de motivo del problema de configuración — junto con un identificador de instalación aleatorio, versión del paquete, nombre y versión del cliente de IA, versión de Node.js y sistema operativo. El token OAuth, los datos de la cuenta, el contenido de los archivos, los argumentos de las herramientas y los textos de las solicitudes no se leen ni se envían. El envío se realiza en segundo plano con un tiempo de espera de 2 segundos y no afecta el funcionamiento del servidor; la implementación está en src/telemetry.ts.

Para desactivar la telemetría, define la variable de entorno:

ASKADS_TELEMETRY=0

Limitaciones

• El procesamiento no es inmediato. Después de confirmar un segmento, verifica su estado a través de la lista de segmentos: pueden aparecer estados de procesamiento, errores y volumen de datos insuficiente.
• La eliminación de un segmento es irreversible. Para el píxel, la API prevé la restauración mediante un método separado, disponible a través de raw_request.
• No se puede solicitar un segmento individualmente. La API devuelve una lista general — el servidor encuentra el segmento deseado por su id en ella.
• Mínimo 100 registros y máximo 1 GB. Al confirmar un segmento más pequeño, puedes pasar check_size: false, pero ese segmento no se puede usar en Direct hasta que el tamaño crezca.
• Cuotas de API. Hasta 30 solicitudes por segundo desde una IP y 5 000 solicitudes por día por cuenta. Creación y modificación de segmentos: hasta 10 por minuto, 100 por hora y 500 por día. Las solicitudes con error también consumen cuota.
• Ante una limitación temporal de la API. El servidor repite la solicitud con un retraso hasta el número de intentos de YANDEX_AUDIENCE_MAX_RETRIES; la respuesta 429 no significa que debas crear el objeto de nuevo.
• Sin supervisión en segundo plano. El servidor solo funciona durante la llamada desde la aplicación de IA y no espera la finalización del procesamiento. Si tu aplicación admite tareas programadas, configura una verificación periódica de estados a través de la lista de segmentos.

Documentación técnica

• Catálogo de capacidades MCP — páginas con tareas de usuario para cada herramienta.
• Todas las herramientas — datos de entrada, respuestas, estados y limitaciones.
• Desarrollo — ejecución local, pruebas, compilación y verificación smoke de solo lectura.
• Publicación — lanzamiento del paquete npm y listado en catálogos MCP.
• Paquete npm — versión publicada de mcp-yandex-audience.
• API de Yandex Audiences — documentación oficial.

Soporte

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