mcp-yandex-merchants

Яндекс Товары MCP

A1 Яндекс Товары MCP conecta una aplicación de IA a la API de socios de Yandex Market. Puedes cambiar precios, descuentos y visibilidad de productos individuales con palabras normales, sin editar ni volver a cargar todo el feed YML. La conexión comienza directamente en el diálogo: no necesitas crear un token ni editar la configuración de antemano.

• 13 acciones listas. Conexión de cuenta directamente desde el diálogo, verificación de acceso, lista de feeds, precios, descuentos, ocultar y restaurar productos, así como llamadas directas a otros métodos de la API.
• Para un solo producto y listas grandes. En una sola solicitud puedes cambiar precios de 2 000 productos u ocultar y restaurar hasta 500 productos.
• Cambios puntuales. El servidor trabaja con el feed YML ya cargado y no crea feeds desde cero.
• Resultado verificable. Una escritura se considera exitosa solo cuando status: "OK" aparece en la respuesta de Yandex Market.
• Funciona localmente. El servidor se inicia mediante npx; el token OAuth permanece en tu computadora.

Prueba con el primer mensaje:

Verifica la conexión con Yandex Market y muestra los feeds disponibles.

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

Ver cómo funciona en un minuto

Tú: Verifica la conexión y muestra mis feeds.

Asistente: Verifica el token y muestra feedId y la dirección de cada feed disponible.

Tú: En el feed 1069 prepara un nuevo precio para SKU-123: 1 490 ₽ en lugar de 1 990 ₽. Primero muestra el cambio.

Asistente: Preparado: feed 1069, producto SKU-123, nuevo precio 1 490 ₽, precio tachado 1 990 ₽. ¿Enviar el cambio?

Tú: Sí, actualiza.

Asistente: Envía el cambio y verifica el campo status en la respuesta. La operación se completa si Yandex Market devuelve status: "OK".

Contenido

• Inicio rápido
• Qué puedes encargar
• 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

Necesitarás Node.js 20 o superior, un feed YML cargado en Yandex Market y el inicio de sesión de Yandex con el que se cargó ese feed. El servidor se inicia mediante npx, por lo que no es necesario instalar un paquete por separado.

1. Agrega el servidor a la aplicación de IA: a continuación se muestra un ejemplo abierto para Codex; las demás aplicaciones están recopiladas en instrucciones plegables.
2. Escribe: «Conecta Yandex Market». El asistente te dará un enlace para iniciar sesión en Yandex y te pedirá que envíes el código de confirmación. Si configuraste YANDEX_MERCHANTS_OAUTH_TOKEN en la configuración, este paso no es necesario.
3. Verifica la conexión: «Verifica la conexión con Yandex Market y muestra los feeds disponibles». Si el servidor devolvió la lista de feeds, puedes pasar a precios y visibilidad de productos.

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

codex mcp list

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

claude mcp list

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

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

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

Este es un servidor MCP local: la aplicación ejecuta npx en tu computadora. Las versiones web de ChatGPT y Claude no pueden iniciar ese proceso por sí solas: usa la aplicación de escritorio, CLI o un editor con soporte para servidores MCP locales.

Qué puedes encargar

Verificar la conexión y elegir un feed

• Verificar el token. Asegurarse de que el servidor vea la cuenta: check_access.
• Mostrar los feeds disponibles. Obtener feedId y la dirección de cada feed: list_feeds.

feedId será necesario para cualquier cambio. La API no muestra el contenido del feed, su estado ni los valores actuales de los productos.

Cambiar precios y descuentos

• Cambiar el precio de un solo producto — set_offer_price.
• Actualizar precios en lista de hasta 2 000 productos en una sola solicitud — update_offer_prices.
• Establecer un descuento con precio nuevo y precio tachado — set_offer_discount.
• Agregar un precio especial para Yandex Pay, SBP o la tarjeta Ozon — set_offer_price.

Los precios se envían solo en rublos. Si en un mismo feed hay varias ofertas con el mismo id, la API cambiará solo la primera.

Ocultar o restaurar productos

• Ocultar un solo producto — hide_offer.
• Ocultar hasta 500 productos con un solo comando — hide_offers.
• Restaurar hasta 500 productos a la vista — show_offers.

Un producto se puede ocultar indefinidamente o por un período de hasta 720 horas. Con la ocultación indefinida, permanecerá invisible hasta que se dé un comando separado para restaurarlo.

Llamar a otros métodos de la API

raw_request permite acceder a un método de la API de socios para el que no existe una acción lista separada. Admite GET, POST y DELETE y acepta datos en el formato original de la API.

raw_request puede modificar datos reales. Si la acción que necesitas ya está entre las herramientas listas, es más seguro usarla.

Los nombres completos de los campos, los formatos de respuesta y los códigos de error están recopilados en la referencia de herramientas.

Cómo funciona

El servidor no crea, elimina ni carga feeds. Toma feedId de un feed YML existente y envía a Yandex Market cambios puntuales para los productos indicados.

Esto es útil cuando necesitas rápidamente:

• corregir uno o varios precios;
• aplicar un descuento;
• ocultar un producto agotado;
• restaurar un producto a la vista.

El feed YML en sí sigue gestionándose a través del panel de Yandex Market o Webmaster. El servidor no puede leer el contenido del feed, por lo que los id de los productos y el registro de cambios deben almacenarse de tu lado.

Qué puede modificar datos

El servidor reduce el riesgo de errores de la siguiente manera:

• verifica los campos obligatorios, los tamaños de las listas, la longitud del id, los precios positivos y el rango de descuento antes de enviar la solicitud;
• verifica status en el cuerpo de la respuesta, porque HTTP 200 no significa aún una escritura exitosa;
• no repite la escritura automáticamente después de un error del servidor o una interrupción de la conexión;
• no permite que raw_request envíe el token OAuth a una dirección externa;
• informa a la aplicación de IA qué acciones leen datos y cuáles los modifican.

La confirmación antes de escribir depende de la aplicación de IA. Si quieres verificar primero los valores, pide al asistente que prepare el cambio, muestre feedId, el id del producto y los nuevos valores, y que lo ejecute solo después de tu siguiente comando.

Conexión y configuración

Para el uso normal, no se necesita un token de antemano:

1. En el chat, pide conectar Yandex Market.
2. Abre el enlace de Yandex OAuth estrictamente con el inicio de sesión de Yandex con el que se cargó el feed YML — el token de otro inicio de sesión no verá ningún feed.
3. Confirma el acceso y envía el código al asistente. El código es de un solo uso y tiene una validez de 10 minutos.

El servidor usa PKCE: el código del chat no se puede intercambiar por un token por sí solo; solo tu servidor en ejecución puede hacerlo. Solicita un único permiso: products:partner-api («API de búsqueda de productos»). El token obtenido se almacena localmente en ~/.config/mcp-yandex-merchants/credentials.json con permisos solo para el propietario y se renueva automáticamente. No es necesario reiniciar la aplicación de IA después del inicio de sesión.

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

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

Si usas tu propia aplicación OAuth, regístrala en oauth.yandex.ru/client/new (plataforma «Servicios web», Redirect URI https://oauth.yandex.ru/verification_code) y agrega el acceso products:partner-api — «API de búsqueda de productos». El token listo para YANDEX_MERCHANTS_OAUTH_TOKEN lo emite la página https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>, abierta con el inicio de sesión que cargó el feed YML. Guarda el token como una contraseña: no agregues la configuración con el token real a Git ni la envíes a terceros.

Datos y telemetría

El servidor se ejecuta en tu computadora y se comunica directamente con https://yandex.ru/products/api/ext/partner. El token OAuth se agrega solo a las solicitudes de esa API: incluso raw_request acepta una ruta relativa y no puede enviar el token a otro sitio. Al iniciar sesión desde el diálogo, el servidor también se comunica con oauth.yandex.ru — solo para intercambiar el código de confirmación por un token y renovarlo. Por defecto, el servidor envía a usage.gistrec.cloud telemetría técnica anónima: un identificador de instalación aleatorio, nombre del evento o herramienta, versión del paquete, versión de Node.js, sistema operativo e información sobre el cliente de IA conectado. No incluye el token OAuth, datos de la cuenta, IDs de feeds y productos, precios, argumentos de herramientas ni textos de solicitudes. El envío se realiza en segundo plano y no afecta el funcionamiento del servidor.

Para desactivar la telemetría para los servidores MCP A1, establezca la variable de entorno:

ASKADS_TELEMETRY=0

Limitaciones

• No se puede leer el estado actual de los productos. La API no devuelve precios actuales, lista de productos ocultos, contenido o estado del feed. Mantenga un registro de cambios en su lado.
• No se pueden gestionar los feeds en sí. Crear, eliminar o recargar un feed YML solo es posible en el panel o en Webmaster.
• Solo rublos. La API no acepta otras monedas.
• ID de producto: hasta 50 caracteres. La API no aceptará identificadores más largos.
• Hasta 2 000 precios por solicitud. Para ocultar y restaurar: hasta 500 productos por solicitud.
• Hasta 50 000 operaciones por minuto. Los cambios de precios y el total de ocultamientos con restauraciones se cuentan por separado.
• Sin reversión automática. Tras una interrupción de la conexión, el resultado de la escritura puede permanecer desconocido y no se puede leer el estado a través de esta API. No repita dicha operación automáticamente.
• Sin monitoreo continuo. El servidor solo funciona cuando la aplicación de IA lo invoca. Si la aplicación admite tareas programadas, puede solicitarle que verifique periódicamente el acceso o ejecute un escenario predefinido.

Documentación técnica

• Catálogo de capacidades MCP — páginas por tareas de usuario para cada herramienta.
• Todas las herramientas — parámetros, respuestas, códigos de error y limitaciones.
• Documentación de desarrollo — ejecución local, verificaciones y compilación.
• Publicación — lanzamiento del paquete npm y publicación en catálogos MCP.
• Paquete en npm.
• API de Yandex Merchants.

Soporte

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