🗄 Repositorio archivado

El desarrollo se ha trasladado a theYahia/WWmcp — un monorepositorio de servidores MCP para APIs no occidentales: CEI, MENA, África, LATAM, Sudeste Asiático. Núcleo común @theyahia/mcp-core, CI unificado, un único pipeline de lanzamiento.

La versión actual de lo que había aquí: servers/wildberries/

El paquete en npm sigue siendo el mismo — @theyahia/wildberries-mcp, se instala y funciona como antes. Aquí ya no se actualiza nada. Las tareas y pull requests — en WWmcp.

Archivado: el desarrollo se trasladó a theYahia/WWmcp, un monorepositorio de servidores MCP para APIs no occidentales. La versión actual de este paquete ahora vive en servers/wildberries/. El paquete npm @theyahia/wildberries-mcp no ha cambiado. Por favor, abre issues y pull requests allí.

@theyahia/wildberries-mcp

Servidor MCP para la API de vendedores de Wildberries: 30 herramientas para productos, precios, existencias, pedidos, ventas, suministros FBS, analíticas, comentarios, preguntas, devoluciones y anuncios. Enrutamiento por host por categoría con limitación de frecuencia y protección contra la penalización 409. Transportes Stdio + Streamable HTTP.

Related MCP server: Wildberries MCP Server

Inicio rápido

npm install -g @theyahia/wildberries-mcp

# stdio transport (for Claude Desktop, Cursor, etc.)
WB_API_TOKEN=your_token wildberries-mcp

# Streamable HTTP transport
WB_API_TOKEN=your_token wildberries-mcp --http

Claude Desktop

Añádelo a claude_desktop_config.json:

{
  "mcpServers": {
    "wildberries": {
      "command": "npx",
      "args": ["-y", "@theyahia/wildberries-mcp"],
      "env": { "WB_API_TOKEN": "your_token_here" }
    }
  }
}

Cursor / Windsurf / VS Code (Copilot) usan el mismo bloque mcpServers en sus ajustes de MCP.

Smithery

npx @smithery/cli install @theyahia/wildberries-mcp

Autenticación y ámbitos de token

Authorization: Bearer {WB_API_TOKEN} (JWT, validez de 180 días). Obtén tu token en el portal del vendedor, en Ajustes → Acceso a la API.

Un único token puede tener varios ámbitos de categoría. Como cada herramienta habla con un host de API distinto, un token al que le falte un ámbito devuelve 401 desde ese host mientras las demás herramientas siguen funcionando. Activa los ámbitos que necesites:

Cuando una llamada falla, el mensaje de error indica el host e incluye el requestId de WB, por lo que un ámbito faltante o un problema de host incorrecto es evidente (p. ej. WB API GET advert-api.wildberries.ru/adv/v1/balance → 401: ...).

Arquitectura: hosts por categoría

La API de vendedores de Wildberries no es una única puerta de enlace. seller.wildberries.ru es el panel web; la API está dividida en hosts por categoría. Cada petición se enruta al host correcto:

Herramientas (30)

Productos y contenido

Pedidos y ventas

Almacenes y suministros FBS

Analítica

Referencia de precios

Comentarios y preguntas

Devoluciones y publicidad

Limitación de frecuencia

Wildberries mide las solicitudes por categoría de API, no como un único grupo global — y devuelve 409 como penalización por ráfagas. El cliente mantiene un limitador de token bucket por host, además de buckets más finos para los endpoints más estrictos:

• Token buckets por host con un intervalo mínimo entre solicitudes.

• Manejo de la penalización 409: lee X-Ratelimit-Retry-After / X-Ratelimit-Remaining, descuenta tokens de penalización y espera la duración indicada antes de reintentar — las penalizaciones permanecen aisladas en la categoría infractora.

• Límites estrictos por endpoint (crear/descargar paid-storage 1/min, estado 1/5s; precios ~10/6s).

Los valores por defecto son deliberadamente conservadores y es seguro aumentarlos una vez que hayas observado los límites reales de tu cuenta. No se necesita configuración.

Configuración

Endpoints HTTP (--http): POST /mcp (solicitudes), GET /health ({ status, version, tools }).

Prompts de demostración

"Enumera los primeros 50 productos de mi catálogo con los precios actuales." "Haz un análisis ABC de los últimos 30 días: ¿qué productos generan el 80% de los ingresos?" "Crea un suministro FBS 'Morning 2026-06-23', añade los pedidos 1001 y 1002, ciérralo para la entrega y obtén su código de barras." "Muestra las preguntas sin responder y redacta una respuesta para la primera." "¿Cuál es mi saldo publicitario y qué campañas están activas?"

Desarrollo

git clone https://github.com/theYahia/wildberries-mcp.git
cd wildberries-mcp
npm install
npm run build
npm test

Licencia

MIT — consulta LICENSE.