wildberries-mcp-ru

wildberries-mcp-ru

API Wildberries para asistentes de IA: ventas y existencias, tarjetas y características, precios y promociones, informes financieros, reseñas. Los diecisiete hosts de WB están organizados en un catálogo.

El paquete levanta un solo servidor, Wildberries, y nada más. El servidor, el catálogo y el núcleo vienen como dependencia de marketplaces-mcp-ru: aquí están el nombre, el punto de entrada y la documentación para un solo marketplace.

Instalación

El paquete está en PyPI, por lo que la línea es una sola:

uvx wildberries-mcp-ru

Si necesitas la rama main en lugar de la versión publicada:

uvx --from git+https://github.com/ilyautov/wildberries-mcp-ru wildberries-mcp-ru

Claude Desktop, claude_desktop_config.json:

{
  "mcpServers": {
    "wb": {
      "command": "uvx",
      "args": ["wildberries-mcp-ru"],
      "env": { "WB_API_TOKEN": "..." }
    }
  }
}

Tercera vía, si el agente admite skills: él mismo instalará el servidor y configurará el cliente.

npx skills add ilyautov/wildberries-mcp-ru

Claves

Dónde obtener el token. Panel de seller.wildberries.ru, sección Configuración, apartado Acceso a la API. El token es uno solo para todos los hosts, pero al crearlo se eligen categorías de acceso: un token emitido solo para contenido no tendrá acceso a las estadísticas.

Cómo se envía en la solicitud. En el encabezado Authorization, y este es un matiz importante: el servidor envía el token crudo sin el prefijo Bearer. Confirmado en la práctica. Si la autenticación falla con un token correcto, revisa esto primero.

Dónde se guarda. En ~/.marketplace-mcp/cabinets.json con permisos chmod 600, localmente. El token no llega al repositorio ni al chat.

variable	secreto	qué es
WB_API_TOKEN	sí	Token del panel de seller.wildberries.ru, Configuración → Acceso a la API. Se envía en Authorization sin Bearer.

Las claves no tienen que estar en el entorno: el servidor admite cuentas y las guarda en ~/.marketplace-mcp/cabinets.json con permisos 600, fuera del repositorio. Se pueden conectar tantas tiendas como sea necesario, y el cambio se hace directamente desde el chat.

Mapa de métodos

El catálogo está en la dependencia como wb_mcp/endpoints.yaml: 307 métodos, de los cuales 187 son de lectura, 108 de escritura y 12 irreversibles. El servidor ejecuta exactamente ese archivo, por lo que la tabla no puede diferir del código.

host	métodos	qué contiene
marketplace-api.wildberries.ru	100	Tareas de picking y envíos FBS, DBS, DBW, recogida propia
seller-analytics-api.wildberries.ru	40	Analítica del vendedor: consultas de búsqueda, existencias, retenciones, almacenamiento de pago
content-api.wildberries.ru	31	Tarjetas de productos, características, categorías, medios, etiquetas
advert-api.wildberries.ru	30	Campañas publicitarias, pujas, clústeres de búsqueda
devapi-digital.wildberries.ru	22	Productos digitales: contenido, ofertas, claves de activación
feedbacks-api.wildberries.ru	20	Reseñas, preguntas, reseñas fijadas
discounts-prices-api.wildberries.ru	13	Precios, descuentos, calendario de promociones
common-api.wildberries.ru	10	Información del vendedor, tarifas, comisiones, noticias
supplies-api.wildberries.ru	7	Envíos al almacén de WB y datos para su preparación
finance-api.wildberries.ru	7	Informes financieros y saldo
statistics-api.wildberries.ru	5	Estadísticas: ventas, pedidos, existencias, informe de ventas
user-management-api.wildberries.ru	4	Usuarios del vendedor y sus permisos
advert-media-api.wildberries.ru	4	Medios en publicidad y sus estadísticas
dp-calendar-api.wildberries.ru	4	Calendario de promociones y participación en ellas
buyer-chat-api.wildberries.ru	4	Chat con compradores
documents-api.wildberries.ru	4	Documentos del vendedor
returns-api.wildberries.ru	2	Devoluciones de compradores

Análisis detallado con parámetros y límites: https://marketplaces-mcp-ru.aifrontier.tech/wildberries-api.html

Qué preguntar en el chat

• muéstrame las ventas en WB de la semana
• saca el informe financiero de ventas del mes pasado
• qué conviene reabastecer, calcula los días de cobertura
• qué productos corren riesgo de quedarse sin stock

Errores frecuentes

401 con token correcto. Dos causas por frecuencia. Primera: WB espera el token crudo en Authorization sin Bearer. Segunda: la cuenta activa en ~/.marketplace-mcp/cabinets.json tiene prioridad sobre las variables de entorno y oculta lo que exportaste.

404 o respuesta vacía en un método que funciona. Revisa el host. WB tiene diecisiete dominios según su propósito, y las estadísticas no responden en el dominio de contenido. La tabla de hosts está arriba.

429, límite de solicitudes superado. Los límites de WB están definidos por método y en algunos casos son muy estrictos: para parte de los métodos es una solicitud por minuto, y para los informes a veces es menos frecuente. El límite está vinculado al método, no a toda la cuenta, por lo que puedes chocar en un solo informe mientras el resto sigue funcionando.

En qué se diferencia de marketplaces-mcp-ru

En nada, salvo en la composición. marketplaces-mcp-ru instala cuatro marketplaces a la vez y los mantiene bajo un mismo servidor; wildberries-mcp-ru instala uno solo. El código es común: una corrección en el núcleo llega aquí mediante una actualización de dependencia, no copiando código.

necesitas	paquete
solo Wildberries	wildberries-mcp-ru
los cuatro marketplaces	marketplaces-mcp-ru

Quién lo hizo

Ilya Utov, laboratorio AI Frontier. Sobre cómo están construidas estas herramientas por dentro, escribo en Telegram y LinkedIn.

También están business-mcp-ru (hh.ru, VK, Diadoc, SBIS, Chestny ZNAK), moysklad-mcp-ru y humanizer-ru.

Todos los proyectos en una sola lista, organizados por propósito: ilyautov.github.io.

Licencia

MIT, ver LICENSE.