Shopify MCP Server

Interactúa con los datos de la tienda Shopify usando la API GraphQL.

Documentación

Servidor MCP de Shopify

(¡deja una estrella si te gusta!)

Servidor MCP para la API de Shopify, que permite la interacción con los datos de la tienda a través de la API GraphQL. Este servidor proporciona herramientas para gestionar productos, clientes, pedidos y más.

📦 Nombre del paquete: shopify-mcp 🚀 Comando: shopify-mcp (no shopify-mcp-server)

Características

Gestión de productos: CRUD completo para productos, variantes y opciones (8 herramientas)
Gestión de clientes: CRUD completo, fusión y gestión de direcciones (8 herramientas)
Gestión de pedidos: Búsqueda inteligente, cancelación, cierre/apertura, marcado como pagado, cumplimiento, reembolsos (10 herramientas)
Gestión de metacampos: Obtener, establecer y eliminar metacampos en cualquier recurso (3 herramientas)
Gestión de inventario: Establecer cantidades absolutas de inventario en ubicaciones (1 herramienta)
Gestión de etiquetas: Añadir/eliminar etiquetas en cualquier recurso etiquetable (1 herramienta)
Paginación y ordenación: Paginación basada en cursores y claves de ordenación en todas las consultas de listas
Filtrado avanzado: Sintaxis de consulta de Shopify de paso directo para todos los endpoints de listas
Integración GraphQL: Integración directa con la API GraphQL Admin de Shopify (2026-01)
Manejo integral de errores: Mensajes de error claros para problemas de API y autenticación

Requisitos previos

Node.js (versión 18 o superior)
Una tienda Shopify con una aplicación personalizada (consulta las instrucciones de configuración a continuación)

Configuración

Autenticación

Este servidor admite dos métodos de autenticación:

Opción 1: Credenciales de cliente (aplicaciones del panel de desarrollo, enero de 2026+)

A partir del 1 de enero de 2026, las nuevas aplicaciones de Shopify se crean en el panel de desarrollo y utilizan credenciales de cliente OAuth en lugar de tokens de acceso estáticos.

Desde tu administrador de Shopify, ve a Configuración > Aplicaciones y canales de venta
Haz clic en Desarrollar aplicaciones > Crear aplicación en el panel de desarrollo
Crea una nueva aplicación y configura los ámbitos de la API de administración:
- read_products, write_products
- read_customers, write_customers
- read_orders, write_orders
Instala la aplicación en tu tienda
Copia tu ID de cliente y Secreto de cliente de las credenciales de API de la aplicación

El servidor intercambiará automáticamente estos por un token de acceso y lo renovará antes de que expire (los tokens son válidos durante ~24 horas).

Opción 2: Token de acceso estático (aplicaciones heredadas)

Si tienes una aplicación personalizada existente con un token de acceso estático shpat_, aún puedes usarlo directamente.

Uso con Claude Desktop

Credenciales de cliente (recomendado):

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": [
        "shopify-mcp",
        "--clientId",
        "<YOUR_CLIENT_ID>",
        "--clientSecret",
        "<YOUR_CLIENT_SECRET>",
        "--domain",
        "<YOUR_SHOP>.myshopify.com"
      ]
    }
  }
}

Token de acceso estático (heredado):

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": [
        "shopify-mcp",
        "--accessToken",
        "<YOUR_ACCESS_TOKEN>",
        "--domain",
        "<YOUR_SHOP>.myshopify.com"
      ]
    }
  }
}

Ubicaciones del archivo de configuración de Claude Desktop:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Uso con Claude Code

Credenciales de cliente:

claude mcp add shopify -- npx shopify-mcp \
  --clientId YOUR_CLIENT_ID \
  --clientSecret YOUR_CLIENT_SECRET \
  --domain your-store.myshopify.com

Token de acceso estático (heredado):

claude mcp add shopify -- npx shopify-mcp \
  --accessToken YOUR_ACCESS_TOKEN \
  --domain your-store.myshopify.com

Alternativa: Ejecutar localmente con variables de entorno

Si prefieres usar variables de entorno en lugar de argumentos de línea de comandos:

Crea un archivo .env con tus credenciales de Shopify:

Credenciales de cliente:

SHOPIFY_CLIENT_ID=your_client_id
SHOPIFY_CLIENT_SECRET=your_client_secret
MYSHOPIFY_DOMAIN=your-store.myshopify.com

Token de acceso estático (heredado):

SHOPIFY_ACCESS_TOKEN=your_access_token
MYSHOPIFY_DOMAIN=your-store.myshopify.com

Ejecuta el servidor con npx:
```
npx shopify-mcp
```

Instalación directa (opcional)

Si quieres instalar el paquete globalmente:

npm install -g shopify-mcp

Luego ejecútalo:

shopify-mcp --clientId=<ID> --clientSecret=<SECRET> --domain=<YOUR_SHOP>.myshopify.com

Opciones adicionales

--apiVersion: Especifica la versión de la API de Shopify (predeterminado: 2026-01). También se puede configurar mediante la variable de entorno SHOPIFY_API_VERSION.

⚠️ Importante: Si ves errores sobre "se requiere la variable de entorno SHOPIFY_ACCESS_TOKEN" al usar argumentos de línea de comandos, es posible que tengas un paquete diferente instalado. Asegúrate de estar usando shopify-mcp, no shopify-mcp-server.

Herramientas disponibles (31)

Paginación, ordenación y filtrado

Todas las herramientas de consulta de listas (get-products, get-customers, get-orders, get-customer-orders) admiten:

Paginación basada en cursores: after / before (cadenas de cursor), con pageInfo en la respuesta (hasNextPage, hasPreviousPage, startCursor, endCursor)
Ordenación: sortKey (enumeración específica de cada recurso) y reverse (booleano)
Filtrado avanzado: parámetro query o searchQuery que acepta sintaxis de consulta de Shopify

Gestión de productos (8 herramientas)

get-products
- Obtener todos los productos o buscar por título con paginación y ordenación
- Entradas:
  - searchTitle (cadena, opcional): Filtrar productos por título (envuelve en title:*...*)
  - limit (número, predeterminado: 10): Número máximo de productos a devolver
  - query (cadena, opcional): Cadena de consulta Shopify sin procesar (p. ej., "status:active vendor:Nike tag:sale")
  - sortKey (cadena, opcional): Uno de CREATED_AT, ID, INVENTORY_TOTAL, PRODUCT_TYPE, PUBLISHED_AT, RELEVANCE, TITLE, UPDATED_AT, VENDOR
  - reverse (booleano, opcional): Invertir el orden de ordenación
  - after / before (cadena, opcional): Cursores de paginación
get-product-by-id
- Obtener un producto específico por ID con detalles completos, incluidos SEO, opciones, medios, variantes y colecciones
- Entradas:
  - productId (cadena, obligatorio): GID del producto Shopify
- Devuelve: productType, descriptionHtml, seo, options (con optionValues), media (imágenes), variants, collections, tags, vendor, rango de precios, inventario
create-product
- Crear un nuevo producto. Al usar productOptions, Shopify registra todos los valores de opciones pero solo crea una variante predeterminada (primer valor de cada opción, precio $0). Usa manage-product-variants con strategy: REMOVE_STANDALONE_VARIANT después para crear todas las variantes reales con precios.
- Entradas:
  - title (cadena, obligatorio): Título del producto
  - descriptionHtml (cadena, opcional): Descripción con HTML
  - handle (cadena, opcional): Slug de URL. Se genera automáticamente a partir del título si se omite
  - vendor (cadena, opcional): Proveedor del producto
  - productType (cadena, opcional): Tipo del producto
  - tags (matriz de cadenas, opcional): Etiquetas del producto
  - status (cadena, opcional): "ACTIVE", "DRAFT" o "ARCHIVED". Predeterminado "DRAFT"
  - seo (objeto, opcional): { title, description } para motores de búsqueda
  - metafields (matriz de objetos, opcional): Metacampos personalizados (namespace, key, value, type)
  - productOptions (matriz de objetos, opcional): Opciones para crear en línea, p. ej., [{ name: "Size", values: [{ name: "S" }, { name: "M" }] }]. Máximo 3 opciones.
  - collectionsToJoin (matriz de cadenas, opcional): GID de colecciones para añadir el producto
update-product
- Actualizar los campos de un producto existente
- Entradas:
  - id (cadena, obligatorio): GID del producto Shopify
  - title (cadena, opcional): Nuevo título
  - descriptionHtml (cadena, opcional): Nueva descripción
  - handle (cadena, opcional): Nuevo slug de URL
  - vendor (cadena, opcional): Nuevo proveedor
  - productType (cadena, opcional): Nuevo tipo de producto
  - tags (matriz de cadenas, opcional): Nuevas etiquetas (sobrescribe las existentes)
  - status (cadena, opcional): "ACTIVE", "DRAFT" o "ARCHIVED"
  - seo (objeto, opcional): { title, description } para motores de búsqueda
  - metafields (matriz de objetos, opcional): Metacampos para establecer o actualizar
  - collectionsToJoin (matriz de cadenas, opcional): GID de colecciones para añadir el producto
  - collectionsToLeave (matriz de cadenas, opcional): GID de colecciones para eliminar el producto
  - redirectNewHandle (booleano, opcional): Si es verdadero, el handle antiguo redirige al handle nuevo
delete-product
- Eliminar un producto
- Entradas:
  - id (cadena, obligatorio): GID del producto Shopify
manage-product-options
- Crear, actualizar o eliminar opciones de producto (p. ej., Talla, Color)
- Entradas:
  - productId (cadena, obligatorio): GID del producto Shopify
  - action (cadena, obligatorio): "create", "update" o "delete"
  - variantStrategy (cadena, opcional): "LEAVE_AS_IS" (predeterminado) o "CREATE" — controla si se generan nuevas combinaciones de variantes al añadir opciones
  - Para action: "create":
    - options (matriz, obligatorio): Opciones para crear, p. ej., [{ name: "Size", values: ["S", "M", "L"] }]
  - Para action: "update":
    - optionId (cadena, obligatorio): GID de la opción a actualizar
    - name (cadena, opcional): Nuevo nombre para la opción
    - position (número, opcional): Nueva posición
    - valuesToAdd (matriz de cadenas, opcional): Valores a añadir
    - valuesToDelete (matriz de cadenas, opcional): GID de valores a eliminar
  - Para action: "delete":
    - optionIds (matriz de cadenas, obligatorio): GID de opciones a eliminar
manage-product-variants
- Crear o actualizar variantes de producto en lote
- Entradas:
  - productId (cadena, obligatorio): GID del producto Shopify
  - strategy (cadena, opcional): Cómo manejar la variante predeterminada al crear. "DEFAULT" (elimina "Título predeterminado" automáticamente), "REMOVE_STANDALONE_VARIANT" (recomendado para control total) o "PRESERVE_STANDALONE_VARIANT"
  - variants (matriz, obligatorio): Variantes para crear o actualizar. Cada variante:
    - id (cadena, opcional): GID de variante para actualizaciones. Omitir para crear nueva
    - price (cadena, opcional): Precio, p. ej., "49.00"
    - compareAtPrice (cadena, opcional): Precio comparativo para mostrar descuentos
    - sku (cadena, opcional): SKU (mapeado a inventoryItem.sku)
    - tracked (booleano, opcional): Si se rastrea el inventario. Establecer false para impresión bajo demanda
    - taxable (booleano, opcional): Si la variante es gravable
    - barcode (cadena, opcional): Código de barras
    - weight (número, opcional): Peso de la variante
    - weightUnit (cadena, opcional): "GRAMS", "KILOGRAMS", "OUNCES" o "POUNDS"
    - optionValues (matriz, opcional): Valores de opción, p. ej., [{ optionName: "Size", name: "A4" }]
delete-product-variants
- Eliminar una o más variantes de un producto
- Entradas:
  - productId (cadena, obligatorio): GID del producto Shopify
  - variantIds (matriz de cadenas, obligatorio): GID de variantes a eliminar

Gestión de clientes (8 herramientas)

get-customers
- Listar clientes con búsqueda, paginación y ordenación
- Entradas:
  - searchQuery (cadena, opcional): Texto libre o sintaxis de consulta Shopify (p. ej., "country:US tag:vip orders_count:>5")
  - limit (número, predeterminado: 10): Número máximo de clientes a devolver
  - sortKey (cadena, opcional): Uno de CREATED_AT, ID, LAST_UPDATE, LOCATION, NAME, ORDERS_COUNT, RELEVANCE, TOTAL_SPENT, UPDATED_AT
  - reverse (booleano, opcional): Invertir el orden de ordenación
  - after / before (cadena, opcional): Cursores de paginación
get-customer-by-id
- Obtener un solo cliente por ID con detalles completos
- Entradas:
  - id (cadena, obligatorio): ID del cliente Shopify (solo numérico, p. ej., "6276879810626")
- Devuelve: nombre, correo electrónico, teléfono, direcciones, etiquetas, nota, estado fiscal, cantidad gastada, número de pedidos, metacampos
create-customer

Crear un nuevo cliente
- Entradas:
  - firstName (cadena, opcional): Nombre del cliente
  - lastName (cadena, opcional): Apellido del cliente
  - email (cadena, opcional): Dirección de correo electrónico del cliente
  - phone (cadena, opcional): Número de teléfono del cliente
  - tags (matriz de cadenas, opcional): Etiquetas a aplicar
  - note (cadena, opcional): Nota sobre el cliente
  - taxExempt (booleano, opcional): Si el cliente está exento de impuestos
  - metafields (matriz de objetos, opcional): Metacampos personalizados (namespace, key, value, type)
  - addresses (matriz de objetos, opcional): Direcciones del cliente (address1, address2, city, provinceCode, zip, country, phone)

update-customer
- Actualizar la información de un cliente
- Entradas:
  - id (cadena, obligatorio): ID de cliente de Shopify (solo numérico, p. ej. "6276879810626")
  - firstName (cadena, opcional): Nombre del cliente
  - lastName (cadena, opcional): Apellido del cliente
  - email (cadena, opcional): Dirección de correo electrónico del cliente
  - phone (cadena, opcional): Número de teléfono del cliente
  - tags (matriz de cadenas, opcional): Etiquetas a aplicar al cliente
  - note (cadena, opcional): Nota sobre el cliente
  - taxExempt (booleano, opcional): Si el cliente está exento de impuestos
  - emailMarketingConsent (objeto, opcional): Configuración de consentimiento de marketing por correo electrónico
    - marketingState (cadena, obligatorio): "NOT_SUBSCRIBED", "SUBSCRIBED", "UNSUBSCRIBED" o "PENDING"
    - consentUpdatedAt (cadena, opcional): Marca de tiempo ISO 8601
    - marketingOptInLevel (cadena, opcional): "SINGLE_OPT_IN", "CONFIRMED_OPT_IN" o "UNKNOWN"
  - metafields (matriz de objetos, opcional): Metacampos del cliente
delete-customer
- Eliminar un cliente
- Entradas:
  - id (cadena, obligatorio): ID de cliente de Shopify (solo numérico, p. ej. "6276879810626")
customer-merge
- Fusionar dos registros de cliente en uno
- Entradas:
  - customerOneId (cadena, obligatorio): GID del primer cliente
  - customerTwoId (cadena, obligatorio): GID del segundo cliente
  - overrideFields (objeto, opcional): Anular qué campos conservar de cada cliente (firstName, lastName, email, phone, defaultAddress, note, tags)
manage-customer-address
- Crear, actualizar o eliminar la dirección postal de un cliente
- Entradas:
  - customerId (cadena, obligatorio): GID del cliente
  - action (cadena, obligatorio): "create", "update" o "delete"
  - addressId (cadena, opcional): GID de la dirección (obligatorio para actualizar/eliminar)
  - address (objeto, opcional): Campos de dirección (obligatorio para crear/actualizar): address1, address2, city, company, countryCode, firstName, lastName, phone, provinceCode, zip
  - setAsDefault (booleano, opcional): Establecer como dirección predeterminada del cliente

Gestión de pedidos (10 herramientas)

get-orders
- Obtener pedidos con filtrado, paginación y ordenación
- Entradas:
  - status (cadena, opcional): "any", "open", "closed" o "cancelled". Predeterminado "any"
  - limit (número, predeterminado: 10): Número máximo de pedidos a devolver
  - query (cadena, opcional): Cadena de consulta de Shopify sin procesar (p. ej. "financial_status:paid fulfillment_status:shipped tag:rush")
  - sortKey (cadena, opcional): Uno de CREATED_AT, ORDER_NUMBER, TOTAL_PRICE, FINANCIAL_STATUS, FULFILLMENT_STATUS, UPDATED_AT, CUSTOMER_NAME, PROCESSED_AT, ID, RELEVANCE
  - reverse (booleano, opcional): Invertir el orden de clasificación
  - after / before (cadena, opcional): Cursores de paginación
get-order-by-id
- Obtener un pedido específico por ID con búsqueda inteligente: acepta nombre de pedido (#77235 o 77235), ID numérico (8054938337547) o GID completo (gid://shopify/Order/...)
- Entradas:
  - orderId (cadena, obligatorio): Nombre de pedido, ID numérico o GID completo
- Devuelve: precios, cliente, direcciones de envío/facturación, artículos de línea, etiquetas, notas, metacampos, motivo de cancelación, estado de devolución, códigos de descuento, número de PO, marcas de tiempo
update-order
- Actualizar un pedido existente
- Entradas:
  - id (cadena, obligatorio): GID de pedido de Shopify
  - tags (matriz de cadenas, opcional): Nuevas etiquetas para el pedido
  - email (cadena, opcional): Actualizar el correo electrónico del cliente en el pedido
  - note (cadena, opcional): Notas del pedido
  - phone (cadena, opcional): Número de teléfono del pedido
  - poNumber (cadena, opcional): Número de orden de compra
  - customAttributes (matriz de objetos, opcional): Atributos personalizados clave-valor
  - metafields (matriz de objetos, opcional): Metacampos del pedido
  - shippingAddress (objeto, opcional): Campos de dirección de envío
get-customer-orders
- Obtener pedidos de un cliente específico con paginación y ordenación
- Entradas:
  - customerId (cadena, obligatorio): ID de cliente de Shopify (solo numérico, p. ej. "6276879810626")
  - limit (número, predeterminado: 10): Número máximo de pedidos a devolver
  - sortKey (cadena, opcional): Mismas claves de ordenación que get-orders
  - reverse (booleano, opcional): Invertir el orden de clasificación
  - after / before (cadena, opcional): Cursores de paginación
order-cancel
- Cancelar un pedido con opciones de reembolso, reposición de inventario y notificación al cliente. Irreversible.
- Entradas:
  - orderId (cadena, obligatorio): GID del pedido
  - reason (cadena, obligatorio): "CUSTOMER", "DECLINED", "FRAUD", "INVENTORY", "OTHER" o "STAFF"
  - restock (booleano, obligatorio): Si se debe reponer el inventario
  - notifyCustomer (booleano, predeterminado: false): Notificar al cliente
  - staffNote (cadena, opcional): Nota interna
  - refund (booleano, opcional): Reembolsar al método de pago original
order-close-open
- Cerrar o reabrir un pedido
- Entradas:
  - orderId (cadena, obligatorio): GID del pedido
  - action (cadena, obligatorio): "close" o "open"
order-mark-as-paid
- Marcar un pedido como pagado (para pagos manuales/fuera de línea)
- Entradas:
  - orderId (cadena, obligatorio): GID del pedido
create-fulfillment
- Crear un cumplimiento (marcar artículos como enviados) con seguimiento opcional
- Entradas:
  - lineItemsByFulfillmentOrder (matriz, obligatorio): Pedidos de cumplimiento y artículos de línea a cumplir
  - trackingInfo (objeto, opcional): { number, url, company } detalles de seguimiento
  - notifyCustomer (booleano, predeterminado: false): Enviar notificación de envío
refund-create
- Crear un reembolso total o parcial con reposición de inventario opcional
- Entradas:
  - orderId (cadena, obligatorio): GID del pedido
  - refundLineItems (matriz, opcional): Artículos de línea a reembolsar con lineItemId, quantity, restockType (CANCEL/RETURN/NO_RESTOCK), locationId
  - shipping (objeto, opcional): { amount, fullRefund } reembolso de envío
  - note (cadena, opcional): Nota de reembolso
  - notify (booleano, opcional): Enviar notificación de reembolso
create-draft-order
- Crear un pedido borrador para ventas por teléfono/chat, facturación o venta al por mayor
- Entradas:
  - lineItems (matriz, obligatorio): Variantes de producto (variantId) o artículos personalizados (title + precio). Máximo 499
  - customerId (cadena, opcional): GID del cliente
  - email, phone, note, tags, poNumber (opcional)
  - shippingAddress, billingAddress (objetos, opcional)
  - appliedDiscount (objeto, opcional): { title, value, valueType } descuento a nivel de pedido

Gestión de pedidos borrador (1 herramienta)

complete-draft-order
- Completar un pedido borrador, convirtiéndolo en un pedido real
- Entradas:
  - draftOrderId (cadena, obligatorio): GID del pedido borrador
  - paymentGatewayId (cadena, opcional): GID de la pasarela de pago

Gestión de metacampos (3 herramientas)

get-metafields
- Obtener metacampos de cualquier recurso de Shopify (productos, pedidos, clientes, variantes, colecciones, etc.)
- Entradas:
  - ownerId (cadena, obligatorio): GID de cualquier recurso
  - namespace (cadena, opcional): Filtrar por espacio de nombres
  - first (número, predeterminado: 25): Número de metacampos a devolver
  - after (cadena, opcional): Cursor de paginación
set-metafields
- Establecer metacampos en cualquier recurso de Shopify. Crea o actualiza hasta 25 metacampos de forma atómica
- Entradas:
  - metafields (matriz, obligatorio): Metacampos a establecer, cada uno con ownerId, key, value y opcional namespace, type
delete-metafields
- Eliminar metacampos de cualquier recurso de Shopify
- Entradas:
  - metafields (matriz, obligatorio): Metacampos a eliminar, cada uno con ownerId, namespace, key

Gestión de inventario (1 herramienta)

inventory-set-quantities
- Establecer cantidades absolutas de inventario para artículos en ubicaciones específicas
- Entradas:
  - reason (cadena, obligatorio): Motivo del cambio (p. ej. "correction", "cycle_count_available")
  - name (cadena, obligatorio): "available" o "on_hand"
  - quantities (matriz, obligatorio): Artículos con inventoryItemId, locationId, quantity

Gestión de etiquetas (1 herramienta)

manage-tags
- Agregar o eliminar etiquetas en cualquier recurso etiquetable (pedidos, productos, clientes, pedidos borrador, artículos)
- Entradas:
  - id (cadena, obligatorio): GID del recurso
  - tags (matriz de cadenas, obligatorio): Etiquetas a agregar o eliminar
  - action (cadena, obligatorio): "add" o "remove"

Referencia de filtros de consulta de pedidos

El parámetro query de la herramienta get-orders admite sintaxis de búsqueda de Shopify:

Filtro	Ejemplo
`name`	`name:#77235`
`created_at`	`created_at:>2024-01-01` o `created_at:2024-01-01..2024-03-31`
`updated_at`	`updated_at:>2024-06-01`
`financial_status`	`financial_status:paid`
`fulfillment_status`	`fulfillment_status:shipped`
`status`	`status:open`
`email`	`email:customer@example.com`
`tag` / `tag_not`	`tag:vip tag_not:wholesale`
`discount_code`	`discount_code:SUMMER20`
`sku`	`sku:PROD-001`
`risk_level`	`risk_level:high`
`gateway`	`gateway:shopify_payments`
`test`	`test:true`

Depuración

Si encuentras problemas, revisa los registros de MCP de Claude Desktop:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Licencia

MIT