Yandex Metrica MCP

Yandex Metrica MCP

Yandex Metrica MCP conecta una aplicación de IA con la analítica web de tu sitio. Pregunta en lenguaje natural de dónde provienen los visitantes, cómo cambia la conversión o dónde crece la tasa de rebote: el asistente tomará los datos de tu contador y explicará el resultado. La conexión comienza directamente en el diálogo: no necesitas crear un token de antemano ni editar la configuración.

• Ocho herramientas. Contadores, objetivos e informes de Metrica, conexión y desconexión de acceso, además de una consulta universal a la API.
• Informes y conversiones. Visitas, usuarios, vistas, rebotes, duración de la visita, fuentes, dispositivos y objetivos durante el período seleccionado.
• 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 contadores inmediatamente después de la conexión.
• Consultas habituales: solo lectura. Las herramientas especializadas no modifican contadores, objetivos ni datos de Metrica.
• Sin recorte silencioso. En el informe se ven los valores finales y el indicador de muestreo; con resultados grandes, el servidor señala si alcanzó el límite.

Prueba con el primer mensaje:

¿Cuántas visitas, usuarios y rebotes tuvo mi sitio durante la última semana?

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

Ver el funcionamiento en un minuto

Tú: Conecta Yandex Metrica.

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

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

Asistente: Conecta Metrica, verifica si los contadores son visibles y comunica el resultado. No es necesario reiniciar la aplicación.

Tú: Durante los últimos 30 días, muestra las fuentes de tráfico y la conversión según el objetivo «Realizar pedido».

Asistente: Encuentra el objetivo, genera un informe por fuentes y muestra visitas, logros del objetivo y conversión. Si Metrica aplicó muestreo, señala que las cifras son aproximadas.

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 necesita Node.js 20 o superior. El servidor se ejecuta mediante npx, por lo que no es necesario instalar el paquete por separado.

1. Agrega el servidor a la aplicación de IA: a continuación se muestra un ejemplo para Codex; las demás aplicaciones están reunidas en instrucciones plegables.
2. Escribe: «Conecta Yandex Metrica». El asistente te guiará a través del inicio de sesión en Yandex y verificará de inmediato que tus contadores sean visibles.
3. Haz tu primera pregunta, por ejemplo: «¿Qué fuentes aportaron más visitas durante el último mes?»

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

codex mcp list

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

claude mcp list

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

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

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

Qué se puede encargar

Entender qué ocurre con el sitio

• «¿Cuántas visitas, usuarios y vistas hubo durante la última semana?»
• «Muestra la dinámica de visitas por día durante junio».
• «¿En qué dispositivos la tasa de rebote es más alta?»

Encontrar la fuente de tráfico y evaluar su calidad

• «Muestra las fuentes de tráfico del mes y ordénalas por visitas».
• «Compara la búsqueda orgánica y la publicidad por usuarios y rebotes».
• «¿Qué fuentes aportaron más transiciones esta semana?»

Analizar las conversiones

• «¿Qué objetivos están configurados en el contador?»
• «¿Cuál es la conversión según el objetivo „Realizar pedido“ en 30 días?»
• «Muestra las fuentes que aportaron más logros del objetivo».

Verificar el acceso y la precisión de los datos

• «¿Qué contadores tengo disponibles?»
• «Muestra el estado de la conexión con Metrica».
• «¿Los datos de este informe son exactos o Metrica usó muestreo?»

Cómo funciona

El servidor trabaja con tres entidades habituales:

Normalmente, el asistente primero encuentra un contador disponible, luego —si es necesario— un objetivo y solo después genera el informe. En la respuesta de Metrica hay un total de todas las filas, el tamaño de la salida y el indicador de muestreo.

Qué puede modificar los datos

El servidor marca la escritura arbitraria como una acción potencialmente destructiva. La forma en que la aplicación de IA solicita confirmación depende de la propia aplicación; antes de esa solicitud, verifica la ruta, el método y los datos.

Conexión y configuración

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

1. En el chat, pide conectar Yandex Metrica.
2. Abre el enlace a Yandex OAuth con la cuenta que tenga acceso a los contadores necesarios.
3. Confirma el acceso y envía el código al asistente. Es válido durante 10 minutos y se convierte en token solo dentro del servidor en ejecución.

El servidor usa PKCE: el código del chat no se puede canjear por un token por sí solo. El token obtenido se almacena localmente en ~/.config/mcp-yandex-metrica/credentials.json con permisos solo para el propietario. Con un refresh-token guardado, el acceso se renueva automáticamente.

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

Si usas tu propia aplicación OAuth, solicita en ella el permiso «Obtención de estadísticas, lectura de parámetros de contadores propios y confiables» (metrika:read).

Datos y telemetría

Por defecto, el servidor envía telemetría técnica anónima: un identificador aleatorio de instalación, el nombre del evento o herramienta, la versión del servidor, la versión de Node.js, el sistema operativo e información sobre el cliente de IA conectado. No incluye el token, los datos de los contadores, los argumentos de las herramientas, tus mensajes ni los valores de las variables de entorno.

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

ASKADS_TELEMETRY=0

Limitaciones

• Muestreo de Metrica. En períodos grandes o informes complejos, la API puede devolver datos aproximados. Consulta los campos sampled y sample_share; para un cálculo más preciso, reduce el período o usa accuracy: "full".
• Tamaño del informe. Una sola solicitud devuelve hasta 10 000 filas. La paginación automática se detiene en un máximo de 100 páginas, 100 000 filas o aproximadamente 1 MB de datos y marca la respuesta incompleta con el campo _truncated.
• Reintentos de solicitudes. El tiempo de espera de una solicitud es de 60 segundos. El servidor hace hasta tres reintentos ante un error temporal: GET — ante un error de red, 429 y 5xx; POST y DELETE — solo ante 429, para no repetir una acción modificadora. La demora tiene en cuenta Retry-After y no supera los 30 segundos.
• Datos reales. Metrica no tiene entorno de pruebas. Las herramientas especializadas leen datos, pero POST y DELETE mediante una consulta arbitraria modifican objetos reales.
• Sin observación en segundo plano. El servidor funciona cuando la aplicación de IA lo invoca y no supervisa las métricas por sí mismo. Si la aplicación admite tareas programadas, se puede configurar una solicitud periódica de informes.

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.
• Documentación de desarrollo — estructura del proyecto y trabajo con la demo.
• Paquete en npm.
• API de Yandex Metrica.

Soporte

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