mcp-wb

Servidor MCP remoto que conecta a Claude con la comunicación con los compradores en Wildberries: reseñas, preguntas y chats. Se despliega como conector personalizado de la organización — cada empleado lo conecta en su Claude, y el token de Wildberries permanece solo en el servidor.

Qué hace

Lectura

Respuestas a clientes: solo mediante borrador

Cada envío se registra en el registro audit con el correo del empleado, el texto y el resultado.

Related MCP server: Meta Cloud API MCP Server

Por qué está organizado así

El token de Wildberries es personal y no sale del servidor. Los límites de WB para la categoría «Preguntas y reseñas» con el token básico son 5 solicitudes por hora, y para los chats, 1 solicitud por hora; no se puede trabajar con ellos. El token personal permite 3 solicitudes por segundo, pero según las reglas de WB está prohibido transferirlo a terceros y usarlo en servicios en la nube: está destinado a sistemas en infraestructura propia o alquilada. De ahí: un VPS propio, un token en el servidor, los empleados acceden mediante OAuth.

La identidad del empleado la establece nuestro servidor. Claude no transmite al servidor MCP ni el correo electrónico ni el ID de usuario, y la opción «servidor sin autorización» no es compatible con el panel de administración de la organización. Por eso, el servidor actúa como servidor de autorización OAuth 2.1 (PKCE, Dynamic Client Registration, RFC 9728/8414) y toma la identidad de Google, Yandex o de un código de un solo uso.

Roles. ALLOWED_EMAIL_DOMAINS / ALLOWED_EMAILS deciden quién puede entrar en general. RESPONDER_EMAILS y ADMIN_EMAILS — quién puede enviar. Los demás reciben un token sin el permiso wb:write y no pueden llamar físicamente a wb_draft_send.

Requisitos

• VPS con IP pública, accesible desde Internet (Claude accede al servidor desde su lado; un servidor detrás de NAT o VPN no servirá)

• Dominio con registro A apuntando a esa IP

• Docker y Docker Compose

• Token personal de WB con las categorías «Preguntas y reseñas» y «Chat con compradores»

• Permisos de Owner o Primary Owner en la organización de Claude (solo ellos agregan conectores)

Despliegue

1. Token de Wildberries

Cuenta personal del vendedor → Configuración → Acceso a la API → Crear token → pestaña «Para integración manual» → tipo Personal. Marque las categorías «Preguntas y reseñas» y «Chat con compradores», nivel de acceso — Lectura y escritura. El token se muestra una sola vez y dura 180 días; configure un recordatorio para reemplazarlo.

2. Configuración

git clone <репозиторий> mcp-wb && cd mcp-wb
cp .env.example .env

Complete el .env. Mínimo obligatorio:

PUBLIC_URL=https://mcp-wb.вашдомен.ru
MCP_DOMAIN=mcp-wb.вашдомен.ru
ACME_EMAIL=admin@вашдомен.ru
WB_TOKEN=<токен из шага 1>
SESSION_SECRET=<openssl rand -hex 32>
ALLOWED_EMAIL_DOMAINS=вашдомен.ru
ADMIN_EMAILS=вы@вашдомен.ru
RESPONDER_EMAILS=менеджер1@вашдомен.ru,менеджер2@вашдомен.ru

Verifique el token antes de iniciar:

npm install && npx tsx scripts/probe-wb.ts

3. Acceso de empleados

Google Workspace (IDENTITY_PROVIDER=google) — en Google Cloud Console cree un cliente OAuth de tipo «Aplicación web», en Authorized redirect URIs agregue:

https://mcp-wb.вашдомен.ru/idp/google/callback

GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET — en .env.

Yandex ID (IDENTITY_PROVIDER=yandex) — aplicación en oauth.yandex.ru, Callback URI:

https://mcp-wb.вашдомен.ru/idp/yandex/callback

Sin IdP externo (IDENTITY_PROVIDER=invite) — emita códigos de un solo uso:

docker compose exec mcp-wb node dist/scripts/invite.js ivan@вашдомен.ru

4. Inicio

docker compose up -d --build

Caddy obtendrá automáticamente el certificado de Let's Encrypt. Verificación:

curl https://mcp-wb.вашдомен.ru/.well-known/oauth-protected-resource/mcp

Debe devolver un JSON con "resource": "https://mcp-wb.вашдомен.ru/mcp".

5. Conexión a la organización de Claude

1. Settings → Connectors en la organización (el elemento solo es visible para el Owner).

2. Add → Custom → Web.

3. URL: https://mcp-wb.вашдомен.ru/mcp

4. No es necesario tocar Advanced settings: el servidor admite Dynamic Client Registration y registrará a Claude automáticamente.

5. Guarde: el conector aparecerá para todos los empleados de la organización.

6. Qué hace cada empleado

Abre Claude → Connectors → encuentra el conector → Connect → inicia sesión con el correo corporativo. Luego puede escribir en lenguaje natural: «muestra las reseñas sin responder de la semana», «prepara una respuesta a la reseña X».

Para verificar sus permisos: wb_whoami.

Operación

Registro de acciones. Todo lo que se envió al comprador está en la tabla audit del archivo de la base de datos:

docker compose exec mcp-wb \
  node -e "const d=require('better-sqlite3')('/data/mcp-wb.db');console.table(d.prepare('SELECT datetime(ts,\"unixepoch\") t,actor,action,target,outcome FROM audit ORDER BY ts DESC LIMIT 30').all())"

Revocar el acceso a un empleado — elimínelo de ALLOWED_EMAILS / desactívelo en Google Workspace y reinicie el contenedor. Los tokens activos verifican la lista de acceso en cada solicitud, por lo que el acceso desaparecerá de inmediato.

Reemplazo del token de WB — cada 180 días: nuevo token en .env, luego docker compose … up -d.

Límites. El cliente mantiene el ritmo por sí mismo: 3 solicitudes/s para reseñas y preguntas, 10 por 10 s para chats, con espera según el encabezado X-Ratelimit-Retry en caso de 429.

Desarrollo

npm install
npm run dev          # tsx watch
npm run typecheck
WB_SANDBOX=true npm run dev   # песочница WB (только отзывы и вопросы, чата в ней нет)

Para una ejecución local de OAuth, configure PUBLIC_URL=http://localhost:3000 e IDENTITY_PROVIDER=invite.

Límites

• Chat: WB no tiene host de sandbox; solo se puede probar en la cuenta de producción.

• Las respuestas a reseñas y preguntas pasan por la moderación de WB y no se publican de inmediato.

• La edición de una respuesta: un intento dentro de 60 días; después, el texto queda fijado para siempre.

• Las solicitudes de devolución (returns-api) requieren una categoría de token separada y no están conectadas en esta versión.

• El servidor funciona sin sesiones: para cada solicitud HTTP se crea una instancia propia del servidor MCP, por lo que no hay notificaciones del servidor hacia el cliente.