marketplace-mcp

Un servidor MCP que permite a los agentes de IA trabajar con cuentas de vendedor de Wildberries / Ozon / Yandex Market: herramientas de lectura tipadas, soporte multi-cuenta, normalización de datos, limitación de frecuencia, auditoría y credenciales cifradas. No es un proxy genérico: las herramientas tienen un espacio de nombres por marketplace (wb_*, ozon_*, ym_*), cada una comprueba los permisos de conexión y devuelve una única forma normalizada.

Estado: v0.3 — superficie de LECTURA en los tres marketplaces. Núcleo, los adaptadores de WB / Ozon / Yandex Market, 17 herramientas. Aún no implementado: ESCRITURA con vista previa/confirmación, recopiladores de historial, publicidad y finanzas. Consulta la hoja de ruta.

El propósito de este proyecto

Una pregunta, una forma de respuesta, independientemente de la plataforma. Los tres marketplaces modelan productos, existencias y pedidos de forma incompatible: en WB una fila de existencias es "una talla en un almacén", en Ozon es "un producto con una matriz de tipos fbo/fbs", en Yandex Market es "almacén → producto → tipos de existencias (AVAILABLE/FREEZE/DEFECT/…)". Este servidor reduce todo a un único esquema, de modo que un agente puede preguntar "¿qué se está agotando?" y obtener una respuesta que cubre tres cuentas:

unified stock list: 9 rows from 3 marketplaces
low stock: wildberries/ZR-002=7, ozon/ZR-002=3
ym dual-path stocks ok: 1 FBS (account) + 2 FBO (shop)

Eso no es una ilustración: es la salida de npm test, que ejecuta los tres adaptadores a través de los mismos esquemas zod.

La segunda línea muestra una peculiaridad honesta de la plataforma: Yandex Market divide las existencias entre dos métodos de API, y una sola llamada físicamente no puede cubrir ambos tipos de almacén. Por lo tanto, una consulta combinada entre tres cuentas devuelve solo los almacenes de vendedor de Yandex Market hasta que el agente pregunte también por los almacenes de Market. El servidor no oculta esto detrás de una agregación "cómoda" que descartaría existencias silenciosamente.

Related MCP server: Yandex Market Seller MCP Server

Inicio rápido sin claves de API (demo)

Sin base de datos, sin tokens: sin DATABASE_URL el servidor arranca con un almacén en memoria y cuentas de vendedor simuladas para los tres marketplaces, rellenas con datos realistas.

npm install
npm run dev            # stdio transport

Conéctalo a Claude Code:

claude mcp add marketplace -- npx tsx /path/to/marketplace-mcp/src/index.ts

Luego pregunta en el chat: "muestra mis conexiones", "¿qué se está quedando sin existencias? — revisa todos los marketplaces", "compara los precios de ZR-002 en las tres cuentas", "¿cuántos pedidos hay esta semana en total?".

Conexión de cuentas de vendedor reales

Las credenciales pueden venir del entorno (modo demo, sin base de datos) o almacenarse cifradas en PostgreSQL (producción).

WB_API_TOKEN=...                          # Wildberries
OZON_CLIENT_ID=... OZON_API_KEY=...       # Ozon
YM_API_KEY=...                            # Yandex Market
npm run dev

Cada plataforma autentica de forma distinta, que es exactamente por qué las credenciales se almacenan como un conjunto de claves en lugar de una única columna de token:

connection_test valida la clave e informa de lo que realmente es accesible: por categoría de API en WB, y la lista de cuentas de negocio y tiendas en Yandex Market.

Entornos de prueba

Ninguno de los tres marketplaces entrega credenciales de prueba públicas: cada sandbox está vinculado a una cuenta de vendedor. Lo que realmente existe:

Una advertencia sobre WB está integrada en el código: no todas las categorías tienen sandbox. "Analítica" no tiene, y ahí es donde viven las existencias, así que en modo sandbox wb_stocks_get habla con la API de producción. El servidor no finge que el aislamiento sea completo: el indicador sandbox es visible en connections_list, y marketplace_capabilities devuelve una sandbox_warning explícita. Todo es de solo lectura, por lo que la cuenta nunca se modifica.

Modo producción

cp .env.example .env    # MASTER_KEY and MCP_AUTH_TOKEN: openssl rand -hex 32
docker compose up --build

Levanta PostgreSQL con migraciones automáticas junto con el servidor en Streamable HTTP: POST /mcp, salud en GET /health.

Seguridad del transporte. Estas herramientas se sitúan delante de las claves de cuentas de vendedor de otras personas, por lo que /mcp está protegido por un token de portador (MCP_AUTH_TOKEN) y validación de Origin (MCP_ALLOWED_ORIGINS, defensa contra DNS rebinding). Sin MCP_AUTH_TOKEN, el servidor se vincula deliberadamente solo a 127.0.0.1 y avisa de ello. En compose, el puerto se publica en loopback: expónlo a través de un proxy inverso TLS. Las claves de cuenta se almacenan como texto cifrado AES-256-GCM; la clave maestra vive fuera de la base de datos.

Arquitectura

MCP client (Claude / ChatGPT / agent)
        │  stdio | Streamable HTTP (stateless, POST /mcp, bearer + Origin)
        ▼
   MCP server ── shared tools: connections_list, connection_test, marketplace_capabilities
        │
        ├─ core: store (Postgres/in-memory) · secrets (AES-GCM) · rate limiter
        │        (token bucket per marketplace+connection+endpoint group) ·
        │        retries (backoff+jitter) · audit (tool_calls) · unified error model
        │
        ├─ adapters/common/schema.ts — THE single normalized schema for all platforms
        │
        ├─ adapters/wb    — Content / Analytics / Statistics / Discounts-Prices APIs
        ├─ adapters/ozon  — Seller API (all methods POST, last_id cursor)
        └─ adapters/ym    — Partner API (businessId → campaignId)

Principios fundamentales:

• Un único esquema para cada plataforma y para los mocks: adapters/common/schema.ts es la única fuente de verdad. Los esquemas sirven también como outputSchemas de las herramientas, de modo que el SDK valida las respuestas, y la suite de pruebas ejecuta además los mapeos de la API real a través de ellos. La deriva de formas falla en tiempo de compilación o en las pruebas, no en la cuenta del cliente.

• Multi-cuenta: cuando existen varias conexiones para un marketplace y se omite connection_id, el servidor devuelve AMBIGUOUS_CONNECTION con la lista, nunca una elección silenciosa. La misma regla se aplica a las cuentas de negocio de Yandex Market (businessId).

• FBO y FBS nunca se fusionan: en las tres plataformas son filas separadas con un fulfillment_model explícito, no un número combinado.

• Modelo de error unificado: AUTH_FAILED, MARKETPLACE_PERMISSION_DENIED, RATE_LIMITED (con retry_after_ms), UPSTREAM_TIMEOUT, … — códigos legibles por IA que llevan un indicador retryable.

• Dinero como cadenas decimales con una moneda, fechas en UTC ISO 8601, y un único contrato de paginación limit/cursor superpuesto a tres mecanismos diferentes (cursor de WB, last_id de Ozon, nextPageToken de Yandex Market).

• Los secretos nunca se registran y nunca aparecen en respuestas, errores o el registro de auditoría; solo el texto cifrado llega a la base de datos.

Herramientas (17)

ym_campaigns_list existe debido al modelo de dos niveles de Yandex Market: una cuenta de negocio (businessId) contiene tiendas (campaignId), y diferentes métodos necesitan identificadores distintos.

Cumplimiento de la API de los marketplaces (verificado el 2026-08-28)

Las rutas, los hosts y los límites se comprobaron contra las especificaciones oficiales en lugar de escribirse de memoria.

Wildberries — de las especificaciones oficiales de OpenAPI:

• GET /api/v1/supplier/stocks se desactivó el 2026-06-23. Las existencias ahora provienen de POST /api/analytics/v1/stocks-report/wb-warehouses (FBO) y .../seller-warehouses (FBS); el token necesita la categoría "Analítica".

• El nuevo método no devuelve el artículo del vendedor (solo nmId), por lo que seller_sku se enriquece desde las tarjetas de producto.

• La autorización es el token sin procesar sin prefijo Bearer: la especificación declara un esquema de seguridad apiKey, y la palabra Bearer nunca aparece en las especificaciones de WB.

Ozon — api-seller.ozon.ru, cada método es un POST, paginación por cursor last_id. Usa /v3/product/list, /v3/product/info/list, /v4/product/info/stocks, /v5/product/info/prices (v4 está obsoleto), /v2/posting/fbo/list, /v3/posting/fbs/list. A fecha de agosto de 2026, ninguno de estos tiene aviso de descontinuación. Ozon no publica una especificación OpenAPI pública, por lo que el contrato se ensambló a partir de documentación y clientes mantenidos; esta es la parte que más necesita verificación con una clave real. Verificado en vivo: Ozon reporta credenciales incorrectas con HTTP 400 (code: 5 / code: 16), no 401, y el cliente lo mapea a AUTH_FAILED.

Yandex Market — api.partner.market.yandex.ru, de la especificación oficial de OpenAPI (github.com/yandex-market/yandex-market-partner-api). Límites tomados de la especificación: GET /v2/campaigns 1000/hora, POST /v3/businesses/{id}/offers/stocks 500/min, POST /v1/businesses/{id}/orders 10000/hora (máx. 50 pedidos por respuesta, ventana ≤30 días). El estado no estándar 420 se trata como límite de frecuencia.

Yandex Market divide las existencias entre dos métodos, algo que el adaptador maneja: POST /v3/businesses/{id}/offers/stocks cubre los almacenes de vendedor (FBS/DBS/Express, y solo funciona sin grupos de almacenes), mientras que POST /v2/campaigns/{campaignId}/offers/stocks cubre los almacenes de Market (FBY → FBO) y es la única vía que funciona cuando existen grupos de almacenes. ym_stocks_get elige la ruta correcta según si se pasó campaign_id; para ver todas las existencias, la herramienta se llama dos veces, algo que se indica explícitamente en su descripción para el agente.

Lo que sigue sin verificar. Los cuerpos de respuesta reales de las tres plataformas: las especificaciones describen el contrato, pero solo una clave real confirma que la producción coincide en cada campo; para eso están previstas pruebas de contrato sobre respuestas grabadas. Ozon es el eslabón más débil (sin especificación pública). También deliberadamente fuera del alcance de v0.3: la marca del producto en Ozon (vive en atributos, una llamada separada) y los nombres de almacén en Ozon y Yandex Market (directorios separados); esos campos devuelven null en lugar de inventarse.

Hoja de ruta

Pruebas

npm test

Sin dependencias externas — un par MCP cliente↔servidor vinculado en memoria. Cubre: tools/list y la presencia de outputSchema en las 12 herramientas de datos, datos simulados para tres plataformas, paginación, separación FBO/FBS, el modelo de error unificado, auditoría, ausencia de secretos en las respuestas, normalización entre marketplaces (3 plataformas × 4 tipos de entidad mediante un mismo conjunto de esquemas), fusión de stocks de tres cuentas en una sola lista, ambas rutas de stock de Yandex Market (FBS de cuenta y FBO de tienda), enrutamiento del host de sandbox de WB (incluidas las categorías que no tienen sandbox), los mapeos de las API reales para WB / Ozon / Yandex Market frente a los esquemas compartidos y el comportamiento del limitador de peticiones.

Los títulos de producto y los nombres de almacén simulados se dejan deliberadamente en ruso: eso es lo que devuelven las API reales de los marketplaces, por lo que la demo se mantiene fiel a los datos de producción.

Licencia

MIT