Wildberries MCP Server

WB MCP Server

Gestiona tus tiendas Wildberries desde el chat con un asistente de IA. 202 herramientas de Seller API — tarjetas, precios, publicidad, suministros, reseñas, finanzas, análisis — disponibles para Claude, Cursor, Copilot, Gemini CLI y cualquier otro cliente MCP. Para vendedores de WB con uno o varios paneles y sin ganas de hacer clic en el panel en lo que se puede preguntar con palabras.

¿También vendes en Ozon? Hay un servidor similar para Ozon.

El servidor lleva más de cinco meses en uso diario, en unos veinte paneles de WB, 202 herramientas. Es una herramienta de trabajo personal del autor y se actualiza según su propia necesidad — cómo exactamente.

Ты: Какие мои карточки заблокированы и почему?
Ты: Покажи ДРР по всем кампаниям за неделю и выключи те, где он выше 15%.
Ты: На каких складах коэффициент приёмки сейчас 0 или 1?
Ты: Ответь на все новые отзывы с оценкой 5 благодарностью.

Qué puede hacer

202 herramientas, agrupadas por secciones de Wildberries Seller API. La lista numerada completa con descripción de cada una — en docs/tools.md.

Tres cosas que normalmente no tienen los servidores similares:

• Multi-tienda. Cada llamada acepta shop_id, por lo que dos paneles de WB conviven en un mismo diálogo. Si hay una sola tienda — shop_id se puede omitir.
• Diagnóstico de WB API. El servidor hace ping a los hosts de WB, realiza solicitudes de prueba ligeras por cada categoría, analiza la caducidad y los permisos del token y resalta «degradaciones»: una herramienta que antes funcionaba y ahora falla de forma estable — señal clara de que WB ha cambiado la API.
• Cifrado de tokens. Los tokens de WB están cifrados (Fernet), no en la configuración del cliente.

Inicio rápido

Opción 1: un solo comando, sin Docker

El servidor funciona por stdio — así lo conectan Claude Desktop, Cursor, VS Code y otros clientes MCP. No hay que compilar nada:

uvx wb-mcp-server

O mediante pip:

pip install wb-mcp-server
wb-mcp

Configuración del cliente (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "wildberries": {
      "command": "uvx",
      "args": ["wb-mcp-server"],
      "env": {
        "WB_API_TOKEN": "ваш токен Wildberries API",
        "DATA_DIR": "~/.wb-mcp"
      }
    }
  }
}

DATA_DIR apunte a cualquier directorio con permisos de escritura — allí se guardan tiendas, claves y estadísticas. Por defecto se usa /data (ruta para Docker).

Opción 2: Docker con interfaz web

Se necesita si quiere un panel, diagnóstico de WB API y una forma cómoda de añadir tiendas a través del navegador. Necesitará Docker (Docker Desktop u OrbStack) y un token de Wildberries Seller API.

git clone https://github.com/DeviceIngineering/wb-mcp-server.git
cd wb-mcp-server
cp .env.example .env          # для локального запуска можно оставить как есть
docker compose up -d --build

Verificación:

curl -s http://localhost:8001/api/health
# {"status":"ok","auth_enabled":false,"health_check_interval_min":30,...}

Lo que se abre:

Después:

1. Abra http://localhost:8001/shops → Añadir tienda → pegue el token de WB → Verificar. El token se obtiene en el portal del vendedor: Configuración → Acceso a API → Crear token (vigencia de 180 días, el resto se ve en la página de diagnóstico).
2. Conecte el cliente MCP — consulte la siguiente sección.
3. Pregunte al asistente: «muestra la lista de mis tiendas en Wildberries» — debería funcionar la herramienta wb_list_shops.

Desglose del comando de inicio:

Detener: docker compose down (los datos quedan en el volumen wb_data). Registros: docker compose logs -f.

git clone https://github.com/DeviceIngineering/wb-mcp-server.git
cd wb-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install .
DATA_DIR=./data PORT=8001 python -m wb_mcp.app

Instalación en clientes

El servidor entrega MCP por SSE: GET /sse — flujo de eventos, POST /messages — mensajes del cliente. El soporte de SSE varía entre clientes, por lo que hay una instrucción específica para cada uno — con rutas de configuración para macOS, Linux y Windows, JSON listo y opciones con y sin token.

Resumen general y tabla de compatibilidad — docs/README.md.

Donde el cliente tiene un comando que configura la conexión por sí mismo, la instrucción empieza con él, y la edición del JSON va como segundo método. La opción más corta — Claude Code:

claude mcp add --transport sse wildberries http://localhost:8001/sse
claude mcp list      # ожидается: wildberries ... ✔ Connected

Multi-tienda y seguridad

Varios paneles. Las tiendas se añaden en /shops, cada una recibe su shop_id. La herramienta wb_list_shops devuelve la lista; 200 de 202 herramientas aceptan shop_id como primer parámetro (excepciones — wb_list_shops y wb_degradations). Si hay una sola tienda, el parámetro se puede omitir: el servidor usará la única disponible.

El sentido no es «saber manejar dos cuentas», sino que la estrategia se escribe una vez y se despliega en todos los paneles: la regla de precios, la plantilla de respuestas a reseñas, el tope de puja en publicidad se aplican a todas las tiendas en un mismo diálogo — sin cambiar de cuenta y sin repartir claves entre configuraciones de distintos clientes. Cuántos paneles se pueden conectar. No hay límite en el código: shops.json — un diccionario normal, añada los que quiera. El tope lo pone no el servidor, sino Wildberries: todos los paneles acceden a WB desde una misma dirección IP — la de donde está este servidor — y los límites se calculan también por dirección. Estimación del autor: unos veinte paneles por una dirección se mantienen en zona segura. Más allá — repartir entre varios servidores con direcciones distintas.

Por qué esto es más importante de lo que parece se ve en los límites de WB: varios métodos tienen 3 solicitudes por minuto, y cualquier respuesta 4XX cuenta como 10 solicitudes. Con una decena de paneles en un servidor, varias solicitudes incorrectas seguidas consumen el límite diez veces más rápido — y chocan contra él todas las tiendas a la vez, no solo donde se equivocaron.

Para vigilar esto hay herramientas:

• Diagnóstico en segundo plano envía un /ping por host por pasada (límite — 3 solicitudes por 30 segundos por host) y guarda las comprobaciones fallidas y advertencias en el historial. La cercanía al límite se ve con antelación, no cuando ya hay bloqueo.
• Detector de degradaciones distingue dos casos: degradación simultánea de muchas herramientas — es throttling por dirección; degradación de una sola — se rompió un endpoint concreto de WB. En el panel se ve de un vistazo.

Dónde están los tokens. En el volumen wb_data (dentro del contenedor — /data):

• shops.json — tiendas, tokens cifrados con Fernet;
• .encryption_key — clave de cifrado, se genera en el primer inicio;
• stats.db — SQLite con estadísticas de llamadas e historial de diagnóstico.

La clave está junto a los datos cifrados, por lo que el cifrado protege contra la fuga accidental de un solo archivo shops.json (copia de seguridad, copiar y pegar), pero no contra quien obtuvo acceso a todo el volumen. Los datos se transfieren con el volumen completo — consulte DEPLOY.md.

Autorización MCP. La variable MCP_AUTH_TOKEN en .env:

openssl rand -hex 32   # значение вписать в .env → MCP_AUTH_TOKEN=
docker compose up -d

• vacía (por defecto) — /sse abierto a todos los que tengan acceso de red al puerto;
• definida — el cliente debe enviar Authorization: Bearer <токен> o ?token=<токен> en la URL. La segunda opción ayuda a clientes que no soportan cabeceras arbitrarias.

El token se verifica en ambos endpoints MCP — tanto en GET /sse como en POST /messages.

Lo que el servidor no hace:

• La interfaz web (/, /shops, /diagnostics) no está protegida por token — accesible a todos los que tengan acceso de red al puerto.
• El puerto 8001 no está pensado para exponerse a internet. Para acceso externo — Tailscale o VPN.
• HTTPS el servidor no lo termina. Si necesita acceso externo por TLS — ponga un reverse proxy.

Interfaz web: se ve cada llamada

En un servidor MCP normal, las llamadas se pierden: qué hizo exactamente el asistente, cuánto tardó y qué respondió el marketplace — no se ve, y uno se entera del problema cuando algo no funcionó. Aquí cada llamada tiene un registro y cada tienda tiene un estado. Para una herramienta que gestiona dinero real en una tienda, esto es una condición de confianza, no un adorno. En cinco meses de uso diario en veinte paneles, estas páginas han acumulado lo que se enumera en la sección sobre límites de WB.

Panel — /

Captura de pantalla — al inicio de la página.

Resumen de todas las llamadas de herramientas (stats.get_summary()):

• total de llamadas, llamadas de hoy, número de errores, duración media de llamada;
• top-10 de herramientas: cuántas veces se llamó, tiempo medio, cuántos errores;
• flujo de las últimas 50 llamadas: hora, tienda, herramienta, duración en milisegundos, éxito o error, texto del error;
• filtro por tienda — conmutador «Todas / panel concreto» sobre el resumen.

Tiendas — /shops

Los gabinetes se agregan y eliminan directamente en el navegador, sin editar archivos ni reiniciar el contenedor. Cada tienda tiene un botón «Verificar»: realiza una solicitud real ligera a WB y dice de inmediato si el token está vivo, en lugar de dejar que lo descubras en el momento de la primera llamada de trabajo. En la lista, los tokens se muestran enmascarados (abc***xyz).

Los tokens se cifran con Fernet y se guardan en shops.json dentro del volumen de datos; la clave está en .encryption_key en el mismo lugar. El pool de clientes HTTP se reinicia al guardar y eliminar una tienda, de modo que el nuevo token se toma de inmediato.

Diagnóstico — /diagnostics

(en la captura — tienda demo con token ficticio: WB responde 401 a cada ping y a cada prueba, por lo que toda la página está en rojo. Así se ve una verificación fallida: el servidor está en buen estado. Con un token real, la línea «Verificación …» muestra ping 13/13, пробы 20/20 y el estado de la tienda es «✅ Saludable».)

Verificación en segundo plano cada HEALTH_CHECK_INTERVAL_MIN minutos (por defecto 30), por cada tienda:

• token — fecha de vencimiento, categorías de acceso, banderas «solo lectura» y «sandbox»;
• ping a 13 hosts de WB API — disponibilidad y latencia de cada uno;
• 20 pruebas — una solicitud GET real ligera por categoría de API. Justamente estas detectan la situación «el endpoint devuelve 404 porque WB lo renombró»;
• advertencias en lenguaje humano: «el token vence en N días», «Contenido: 404 en /content/v2/... — posiblemente WB cambió la API»;
• historial de verificaciones con rotación automática (se guardan las últimas 1000 entradas);
• botón «Verificar ahora» — ejecutar todo de inmediato.

Detector de degradaciones

Lo más útil que aporta la estadística acumulada. El servidor encuentra por sí mismo las herramientas que antes funcionaban y ahora fallan de forma estable: las últimas tres llamadas son errores, aunque en el historial hubo llamadas exitosas. Para cada una de estas herramientas se muestran el momento de la última llamada exitosa, el número de errores consecutivos, el texto del último error y el momento en que todo se rompió.

Es decir, el servidor detecta por su propia estadística que Wildberries rompió o deshabilitó un endpoint — y lo comunica antes de que te topes con ello en el trabajo. Junto a la sección sobre límites y plazos de desactivación de endpoints es su continuación práctica: allí se enumera lo que WB ya anunció; aquí, lo que hizo en silencio.

Se puede ver en el panel o con la herramienta wb_degradations — directamente desde el chat.

JSON para monitoreo externo

Todo lo que se ve a simple vista también se obtiene por máquina:

Así que el servidor se puede colgar en Uptime Kuma, Zabbix o cualquier otro monitoreo y enterarse de un token roto antes de que el asistente lo cuente.

Cómo está hecho

Un solo contenedor Docker, dentro una aplicación FastAPI que combina dos roles: servidor MCP por SSE y una pequeña interfaz web. Un archivo por párrafo:

• wb_mcp/server.py — el propio servidor MCP. La lista TOOLS de 202 objetos Tool (nombre, descripción, esquema JSON de argumentos) es lo que el cliente recibe en respuesta a tools/list. Las llamadas se distribuyen con tres diccionarios: NO_CLIENT_DISPATCH (no necesita acceso a WB), CLIENT_DISPATCH (necesita el cliente HTTP de la tienda), SHOP_DISPATCH (necesita además shop_id). Aquí también vive el punto de entrada stdio main() — por si hay un cliente que solo soporta stdio.
• wb_mcp/client.py — clientes HTTP de 14 hosts de Wildberries. Un WBClient por tienda, dentro httpx.AsyncClient con el token; los clientes se cachean en un pool por shop_id.
• wb_mcp/app.py — FastAPI: GET /sse y POST /messages para MCP, páginas del panel, tiendas y diagnóstico, JSON-API /api/*, verificación MCP_AUTH_TOKEN, ciclo en segundo plano de health-checks.
• wb_mcp/settings.py — tiendas y claves: lectura y escritura de shops.json, cifrado Fernet, migración del antiguo settings.json de un solo gabinete, enmascarado de tokens para la UI. Hay fallback: si se define la variable WB_API_TOKEN, aparece la tienda default.
• wb_mcp/diagnostics.py — ping a hosts de WB, decodificador de token JWT (vencimiento, permisos, sandbox), «pruebas» — una solicitud real ligera por categoría de API, noticias de WB.
• wb_mcp/stats.py — SQLite mediante aiosqlite: cada llamada de herramienta se registra con hora, éxito y shop_id; de aquí salen el detector de degradaciones y el historial de health-checks.
• wb_mcp/templates/ — tres páginas con PicoCSS, sin compilar frontend.

Puntos poco evidentes:

• shop_id se rellena solo mientras haya una sola tienda. Cómodo en el día a día, pero al agregar un segundo gabinete, las solicitudes sin shop_id empezarán a devolver «Especifique shop_id».
• Cada llamada se registra en la estadística, incluidas las fallidas. De ahí funciona el detector de degradaciones: «antes funcionaba, ahora falla de forma estable» es señal de un cambio en la API de WB, no de un error tuyo. Ver: herramienta wb_degradations o panel.
• El diagnóstico en segundo plano cada 30 minutos hace solicitudes reales a WB y consume límites. Si molesta, ponga HEALTH_CHECK_INTERVAL_MIN=0 en .env.
• Las respuestas se devuelven tal cual, JSON crudo de WB, sin reempaquetar. Las herramientas son predecibles por eso, pero los informes grandes conviene pedirlos con filtros; si no, la respuesta se come el contexto.
• POST /messages está montado como aplicación ASGI separada (Mount), no como ruta normal de FastAPI: handle_post_message envía la respuesta ASGI por sí mismo, y dentro de una ruta el framework la enviaría por segunda vez — la conexión se rompería en cada POST. Por eso la autorización para este endpoint se verifica manualmente dentro de la aplicación.
• La versión de la librería mcp está fijada como >=1.0.0,<2. El servidor está escrito para la API de decoradores de mcp 1.x (@app.list_tools()); en mcp 2.0 la quitaron. No quite el límite superior en pyproject.toml: con mcp 2.x el servidor falla al arrancar con AttributeError: 'Server' object has no attribute 'list_tools'.

Variables de entorno

Limitaciones de la API de Wildberries

Son limitaciones del propio WB, no del servidor — pero el asistente se topará con ellas con regularidad, y es mejor saberlo de antemano. La lista no es una copia de la ayuda: son cinco meses de llamadas diarias en unas veinte cuentas más el registro de diagnóstico.

• GET /adv/v3/fullstats (estadísticas de publicidad) — 3 solicitudes por minuto, período no mayor a 31 días.
• Embudo de ventas v3 — 3 solicitudes por minuto; el historial por días está disponible como máximo de la última semana.
• /ping — 3 solicitudes cada 30 segundos por host (el diagnóstico en segundo plano lo tiene en cuenta).
• Cualquier respuesta 4XX cuenta como 10 solicitudes para el límite de WB (regla desde el 04.06.2026). Un parámetro incorrecto en un bucle — y ya llegaste al límite.
• reportDetailByPeriod se elimina el 15.07.2026; el servidor ya usa finance-api con fallback al endpoint antiguo.
• La creación de suministros FBW por API no es posible — solo en el panel personal. Las herramientas wb_fbw_* son informativas.
• El token de WB dura 180 días. El resto lo muestran wb_token_info y la página /diagnostics.
• La respuesta 429 de WB es un límite, no una avería. Repita en un minuto.

Verificado con la documentación de dev.wildberries.ru a junio de 2026.

Referencia técnica

Hosts de Wildberries Seller API

Diagnóstico

• Página /diagnostics — por cada tienda: vencimiento del token y sus permisos, ping a todos los hosts de WB API, pruebas por categorías, historial de verificaciones, botón «Verificar ahora».
• Autoverificación en segundo plano cada HEALTH_CHECK_INTERVAL_MIN minutos.
• Detector de degradaciones — resalta en el panel las herramientas que dejaron de funcionar.
• Herramientas MCP: wb_diagnostics, wb_token_info, wb_degradations, wb_api_news.
• GET /api/health — resumen JSON para monitoreo externo.
• POST /api/diagnostics/run — ejecutar la verificación de todas las tiendas ahora mismo.
• GET /api/diagnostics/<shop_id> — diagnóstico completo de una tienda.

Estructura del proyecto

wb-mcp-server/
├── docker-compose.yml          # порт 8001, том wb_data
├── Dockerfile                  # python:3.12-slim
├── pyproject.toml
├── DEPLOY.md                   # деплой на отдельную машину, перенос данных
├── docs/                       # подключение клиентов + справочник инструментов
└── wb_mcp/
    ├── server.py       # MCP-сервер: 202 инструмента, диспетчеризация, stdio-режим
    ├── client.py       # HTTP-клиенты 14 API Wildberries
    ├── app.py          # FastAPI: SSE + веб-интерфейс + авторизация + health-loop
    ├── diagnostics.py  # ping, JWT-декодер, пробы, новости API
    ├── settings.py     # магазины и ключи (Fernet)
    ├── stats.py        # статистика вызовов и история проверок (SQLite)
    └── templates/      # PicoCSS: dashboard, diagnostics, shops

Despliegue

Poner el servidor en una máquina aparte, trasladar las tiendas, configurar el arranque automático — ver DEPLOY.md.

El mismo servidor para Ozon

DeviceIngineering/ozon-mcp-server — la misma herramienta para otro marketplace: misma arquitectura, misma interfaz web con panel y diagnóstico, misma multi-tienda mediante shop_id, mismo transporte SSE y las mismas formas de conexión a los clientes. Si entendiste uno, el segundo se lanza con la misma instrucción; difieren el puerto y el conjunto de herramientas.

Se pueden tener simultáneamente en una misma máquina: los puertos son distintos, los datos en volúmenes Docker diferentes, no hay conflicto.

La convivencia en un mismo servidor tampoco estorba con los límites: ambos salen hacia afuera desde la misma IP, pero Wildberries y Ozon cuentan los límites cada uno por su lado — son plataformas distintas. La restricción por número de cuentas, mencionada en la sección sobre multi-tienda, aplica por separado dentro de cada plataforma.

Actualizaciones y soporte

Wildberries cambia la API constantemente: los endpoints se agregan, renombran y desactivan — en la sección sobre limitaciones se enumera lo que ya se ha detectado en la práctica. Este servidor es una herramienta de trabajo del autor: más de cinco meses de uso diario en unas veinte cuentas. Se actualiza según su propia necesidad: cuando un cambio rompe algo en sus tiendas, no por calendario. Por eso los intervalos entre commits pueden ser largos — significa que WB no rompió nada en ese tiempo. No hay compromisos de plazos.

Si se necesita una corrección urgente — escriba a d0371153@gmail.com. Los issues y pull requests también son bienvenidos y se revisan.

Licencia

MIT — ver LICENSE.