Cin7 Omni MCP Server

An MCP server that gives Claude full access to the Cin7 Omni API — every resource and every operation the API supports:

Contacts · Branches · Product Categories · Products · Product Options · Product Images · Size Ranges · Stock · Serial Numbers · Branch Transfers · Adjustments · Vouchers · Sales Orders (incl. cartons) · Payments · Payment Fees & Payouts · Purchase Orders · Quotes · Credit Notes · BOM Masters (v1 & v2) · Production Jobs · Users · Cartons

La matriz de verbos (qué recursos se pueden listar, obtener, crear, actualizar o eliminar) se toma de la especificación swagger oficial de Cin7 y el servidor la hace cumplir, por lo que Claude nunca puede intentar una operación que la API no admita.

Tools

Las lecturas y las escrituras son herramientas separadas con las anotaciones MCP adecuadas (readOnlyHint, destructiveHint), por lo que en Claude puedes configurar cada herramienta de escritura como Permitir siempre, Preguntar cada vez o Denegar, de forma independiente de las lecturas.

Related MCP server: GHL MCP Server

Instalar en Claude Desktop (3 pasos, sin editar configuración)

1. Obtén tus credenciales de la API de Cin7 — en Cin7 Omni: Settings (⚙) → Integrations → API v1 → Add API Connection. Esto te proporciona un API Username y una API Key (credenciales Basic-auth, no tu inicio de sesión de Cin7). Concede a la conexión permiso para los módulos a los que quieras que Claude acceda: un módulo sin permiso devuelve 403.

2. Descarga dist/cin7-omni.mcpb — un solo archivo, ~150 KB.

3. Ábrelo — haz doble clic en el archivo (o en Claude Desktop: Settings → Extensions → arrastra el archivo) y haz clic en Install. Pega el API Username y la API Key cuando se te pida; la clave se almacena en el llavero de tu ordenador, nunca en un archivo. También hay un interruptor de modo de solo lectura si quieres que Claude se limite solo a consultas.

Luego pregúntale a Claude algo como "describe el recurso SalesOrders de Cin7" para confirmar que funciona.

Para desinstalarlo más tarde: Claude Desktop → Settings → Extensions → Cin7 Omni → Uninstall.

Otras formas de ejecutarlo

Un servidor precompilado y autocontenido también se incluye en el repositorio (dist/index.js — todas las dependencias empaquetadas), por lo que con clonar el repositorio basta para ejecutarlo: no hace falta npm install ni ningún paso de compilación. git pull siempre te da la última compilación lista para probar.

git clone https://github.com/panagiotis1226/cin7-omni-mcp.git

Solo si editas el código fuente tú mismo: npm install (que compila automáticamente) o npm run build para recompilar.

Claude Code:

claude mcp add cin7-omni \
  -e CIN7_API_USERNAME=YourApiUsername \
  -e CIN7_API_KEY=your-api-key \
  -- node /absolute/path/to/cin7-omni-mcp/dist/index.js

Claude Desktop (configuración manual) — añade a claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "cin7-omni": {
      "command": "node",
      "args": ["/absolute/path/to/cin7-omni-mcp/dist/index.js"],
      "env": {
        "CIN7_API_USERNAME": "YourApiUsername",
        "CIN7_API_KEY": "your-api-key"
      }
    }
  }
}

Variables de entorno

Control del acceso de escritura

Dos capas:

1. Permisos por herramienta de Claude — cuando Claude llama por primera vez a cin7_create, cin7_update, cin7_delete o cin7_upload_product_image, se te pregunta y puedes elegir permitir una vez, permitir siempre o denegar por herramienta (en Claude Code, gestiona estos ajustes en /permissions).

2. Bloqueo estricto en el servidor — establece CIN7_READ_ONLY=true y las herramientas de escritura no se registran en absoluto.

Límites de peticiones

Cin7 impone 3 llamadas/segundo, 60/minuto, 5.000/día. El servidor pone en cola las peticiones en el lado del cliente para mantenerse dentro de los límites por segundo/minuto y reintenta automáticamente en caso de 429/5xx con backoff, por lo que los escaneos grandes de varias páginas son lentos por diseño. Usa filtros where (p. ej. modifiedDate>='...') y el parámetro fields para minimizar las llamadas.

Ejemplos de prompts

• "¿Cuánto stock de CTS001 tenemos en todas las sucursales?" → cin7_list sobre Stock con where: "code='CTS001'"

• "Muéstrame los pedidos de venta despachados esta semana por más de $500" → cin7_list sobre SalesOrders con un filtro where

• "Crea una orden de compra para el proveedor X con estas líneas…" → cin7_describe PurchaseOrders y luego cin7_create

• "¿Qué campos tiene un Contact?" → cin7_describe Contacts

Desarrollo

npm test           # builds, then runs the stdio smoke test against a mock Cin7 API
npm run build:mcpb # rebuild + validate manifest + repack dist/cin7-omni.mcpb
npm run dev        # run from source with tsx

La compilación genera dos bundles a partir de la misma fuente: dist/index.js (ESM, para clonar y ejecutar / Claude Code) y server/index.cjs (CJS, empaquetado en la extensión .mcpb).

src/fieldReference.ts se genera a partir de la especificación swagger oficial de Cin7 mediante scripts/gen_fields.py (espera swagger.json de https://api.cin7.com/api/swagger/v1/swagger.json en el directorio de trabajo) — regenéralo si Cin7 actualiza su API.

No cubierto

• Los webhooks de Cin7 Omni (notificaciones push) — este servidor es solo de petición/respuesta.

• Cualquier cosa que Cin7 no exponga a través de la API v1/v2.

• Despliegue remoto/HTTP — este es un servidor local stdio; se podría añadir un punto de entrada streamable-HTTP más adelante.