sellercloud-mcp

El primer servidor del Protocolo de Contexto de Modelo (MCP) para SellerCloud. Conecta Claude a tu catálogo, inventario, pedidos y listados de canales: solo lectura, en cinco minutos.

Por qué existe esto

SellerCloud no tiene un SDK público. Su API REST está bien documentada pero no tiene marca: cada equipo que automatiza procesos con ella termina escribiendo desde cero el mismo código de autenticación y paginación.

Si utilizas Claude (o cualquier asistente de IA compatible con MCP) para gestionar el comercio electrónico en el día a día, esa brecha es la diferencia entre que "resumir los pedidos de hoy" funcione de inmediato y que requiera una integración personalizada.

sellercloud-mcp cierra esa brecha. Es un servidor MCP pequeño, bien probado y con licencia MIT que expone siete endpoints de SellerCloud de solo lectura a cualquier cliente MCP. Construido a partir de años de experiencia ejecutando automatización de comercio electrónico a gran escala.

Related MCP server: Amazon Marketplace MCP Server by CData

Qué puedes hacer con él

Conecta este servidor a Claude Code, Claude Desktop o cualquier host MCP, y luego pregunta cosas como:

• "Busca cualquier SKU que contenga WIDGET y muéstrame los niveles de inventario."

• "¿Cuántos pedidos enviamos ayer en todos los mercados? Agrúpalos por canal."

• "Obtén el pedido 100001 y dime qué artículos se enviaron."

• "Enumera los canales configurados para la empresa 9001 y muestra cuáles están activos."

• "Para el SKU ACME-001, compara el precio en todos los listados de canales."

Claude lee tu catálogo directamente. Sin copiar y pegar, sin hojas de cálculo, sin tuberías personalizadas.

Herramientas (v0.1, todas de solo lectura)

Los endpoints de escritura (crear pedido, actualizar inventario, enviar cambios de canal) intencionalmente no están en la v0.1. Están planificados para la v0.2 una vez que la ergonomía de solo lectura se estabilice.

Instalación

pip install sellercloud-mcp

La v0.1 se distribuye desde este repositorio. La publicación en PyPI está pendiente; por ahora, instálalo con pip install git+https://github.com/alveyautomation/sellercloud-mcp o clónalo y ejecuta pip install -e . localmente.

Configurar credenciales

El servidor lee todo desde variables de entorno. Copia .env.example a .env y completa tu tenant:

SELLERCLOUD_API_URL=https://your-team.api.sellercloud.com/rest/
SELLERCLOUD_USERNAME=your-username
SELLERCLOUD_PASSWORD=your-password
SELLERCLOUD_DEFAULT_COMPANY_ID=        # optional fallback
SELLERCLOUD_HTTP_TIMEOUT=60            # optional, seconds
SELLERCLOUD_MAX_RETRIES=3              # optional

Usa una cuenta de SellerCloud de solo lectura. La v0.1 solo llama a endpoints GET, pero la defensa en profundidad significa que debes proporcionar al servidor un usuario dedicado que no pueda modificar nada. Cuando llegue la v0.2 con herramientas de escritura, opta por actualizar la credencial, nunca al revés.

Conectar a Claude Code

Añade a ~/.claude/claude_code_config.json (o a la configuración MCP de tu proyecto):

{
  "mcpServers": {
    "sellercloud": {
      "command": "sellercloud-mcp",
      "env": {
        "SELLERCLOUD_API_URL": "https://your-team.api.sellercloud.com/rest/",
        "SELLERCLOUD_USERNAME": "your-username",
        "SELLERCLOUD_PASSWORD": "your-password",
        "SELLERCLOUD_DEFAULT_COMPANY_ID": "9001"
      }
    }
  }
}

Reinicia Claude Code. Las siete herramientas sellercloud_* aparecerán en cualquier sesión nueva.

Conectar a Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows) y añade el mismo bloque mcpServers de arriba. Reinicia la aplicación de escritorio.

Referencia de herramientas

Cada herramienta devuelve un sobre JSON:

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "human-readable message" }

sellercloud_search_products

sellercloud_search_products(
    query: str,                          # required
    company_id: int | None = None,       # falls back to default if unset
    page: int = 1,
    page_size: int = 50,                 # capped at 50 by SellerCloud
)

Respuesta de ejemplo:

{
  "ok": true,
  "data": {
    "items": [
      { "ID": "ACME-WIDGET-001", "ProductName": "Acme Widget, Standard", "Price": 29.99 }
    ],
    "total": 1,
    "page": 1,
    "page_size": 50
  }
}

sellercloud_get_product

sellercloud_get_product(sku: str, company_id: int | None = None)

Devuelve el registro del catálogo, o data: null si el SKU no está en el catálogo de la empresa.

sellercloud_search_orders

sellercloud_search_orders(
    date_from: str,                      # ISO date "YYYY-MM-DD"
    date_to: str,                        # ISO date "YYYY-MM-DD"
    company_id: int | None = None,
    query: str | None = None,
    limit: int = 200,                    # max 1000
)

Paginación manejada de forma transparente: SellerCloud limita el tamaño de página a 50, pero la herramienta recopila páginas hasta el limit. La respuesta incluye limit_reached: true cuando hubo más pedidos de los permitidos por limit.

sellercloud_get_order

sellercloud_get_order(order_id: int)

Devuelve el registro completo del pedido (con Items[]), o data: null para un 404.

sellercloud_get_inventory

sellercloud_get_inventory(sku: str, company_id: int | None = None)

El registro devuelto incluye:

• InventoryAvailableQty: lo que la API considera vendible en este momento

• PhysicalQty: cantidad disponible físicamente

• ReservedQty: reservada para pedidos abiertos

• OnOrder: cantidad entrante en órdenes de compra

Usa InventoryAvailableQty como el número canónico de "cantidad que puedo vender".

sellercloud_list_channels

sellercloud_list_channels(company_id: int | None = None)

Devuelve la lista de feeds de canales configurados para la empresa. Cada registro incluye ChannelID, Name y Active.

sellercloud_get_channel_listing

sellercloud_get_channel_listing(channel_id: int, sku: str)

Detalle de listado por canal. Útil para verificar precios en diferentes mercados.

Desarrollo local

git clone https://github.com/alveyautomation/sellercloud-mcp
cd sellercloud-mcp
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                                # 44 tests, ~4s

Hooks de pre-commit (gitleaks, ruff, formateador, limpiador de huellas de tenant):

pip install pre-commit
pre-commit install

Las pruebas de integración contra una cuenta sandbox real de SellerCloud están protegidas detrás de SELLERCLOUD_INTEGRATION_TESTS=1. No son necesarias para una contribución normal.

Solución de problemas

Failed to obtain SellerCloud token: nombre de usuario/contraseña rechazados. Causa más común: la cuenta tiene 2FA habilitado o está bloqueada. El endpoint POST /api/token de SellerCloud espera una cuenta de servicio sin 2FA.

Missing required environment variables: el servidor intentó iniciarse antes de que se cargara su .env. Exporta las variables en el shell principal o asegúrate de que la configuración de tu host MCP las incluya en el bloque env.

Resultados vacíos a pesar de datos conocidos: confirma que el company_id es correcto. SellerCloud devuelve solo la empresa predeterminada del usuario autenticado a menos que pases companyID explícitamente.

La paginación se siente lenta: el tamaño de página está limitado a 50 por SellerCloud, no por nosotros. Para rangos de fechas grandes, espera múltiples viajes de ida y vuelta.

Contribución

Las incidencias y solicitudes de extracción (pull requests) son bienvenidas. Por favor:

• Ejecuta pytest antes de abrir un PR (pip install -e ".[dev]").

• Ejecuta pre-commit run --all-files.

• Mantén las adiciones al alcance de la v0.1 solo de lectura. Los endpoints de escritura llegarán en la v0.2.

• Solo datos sintéticos en las pruebas: nada de SKUs reales, nombres de clientes o números de pedido.

Licencia

MIT: consulta LICENSE.

Descargo de responsabilidad

sellercloud-mcp es una integración de terceros no oficial. No está respaldada, afiliada ni apoyada por SellerCloud, Inc. "SellerCloud" es una marca comercial de SellerCloud, Inc. Úsalo bajo tu propio riesgo; verifica el comportamiento con tu tenant antes de depender de él para decisiones de producción.