mcp-shopify-admin

Shopify Admin MCP

Español | Русский

A1 Shopify Admin MCP conecta aplicaciones de IA a una tienda de Shopify a través de la API GraphQL de Admin. Pregunta en lenguaje natural sobre productos, pedidos, clientes, inventario, descuentos y datos de la tienda; el asistente utiliza las herramientas listas del servidor y muestra el resultado.

• Una tienda por servidor. El dominio de la tienda y las credenciales provienen de la configuración; las herramientas no pueden cambiar a otra tienda.
• Los tokens se mantienen frescos. Dale al servidor el ID de cliente y el secreto de una aplicación del Shopify Dev Dashboard y él mismo genera el token de API de Admin, lo mantiene solo en memoria y lo regenera antes de que expire a las 24 horas. Un token ya preparado de una aplicación personalizada antigua también funciona.
• 16 herramientas enfocadas. Lee datos de la tienda, productos, pedidos, clientes, ubicaciones, inventario y descuentos, además de crear o actualizar los registros compatibles.
• Los fallos de GraphQL se muestran. Shopify puede devolver HTTP 200 para una mutación fallida, por lo que el servidor verifica userErrors y rechaza respuestas GraphQL vacías o mal formadas.
• Respuestas conscientes del costo. Cada resultado incluye el bloque de costo de GraphQL: el costo de la solicitud y los puntos disponibles actualmente para las próximas llamadas.
• El riesgo es visible. Las lecturas son de solo lectura; las escrituras de productos, precios, inventario y descuentos son explícitas; la cancelación de pedidos y GraphQL arbitrario están marcados como destructivos.

Comienza con una solicitud de solo lectura:

Muestra los pedidos más recientes y los productos que actualmente tienen inventario.

Conectar el servidor · Explorar casos de uso · Abrir documentación técnica

Véalo funcionar en un minuto

Tú: Muestra los pedidos más recientes y los productos que actualmente tienen inventario.

Asistente: Muestra pedidos recientes con sus estados y totales, luego productos con precios e inventario. No cambia nada.

Tú: Prepara un código de descuento del 20% llamado SUMMER por dos semanas.

Asistente: Muestra el código propuesto, el porcentaje, las fechas y los límites, luego pide confirmación antes de crearlo.

Tú: Confirmar.

Contenido

• Inicio rápido
• Qué puedes pedirle que haga
• Qué puede cambiar en Shopify
• Obtener acceso
• Configuración
• Datos, límites y trabajo en segundo plano
• Documentación técnica
• Soporte

Inicio rápido

Necesitas Node.js 20+, un dominio de tienda como my-store.myshopify.com y credenciales de API de Admin. El conjunto recomendado es el ID de cliente y el secreto de una aplicación del Shopify Dev Dashboard: el servidor los intercambia por un token de acceso él mismo y mantiene ese token fresco, lo cual importa porque el token que Shopify emite para esta concesión expira después de 24 horas. La aplicación y la tienda deben pertenecer a la misma organización de Shopify.

1. Obtén acceso y prepara el ID de cliente y el secreto de cliente de la aplicación.
2. Agrega el servidor MCP a tu aplicación de IA.
3. Envía la solicitud segura de la sección inicial.

El servidor se ejecuta localmente a través de stdio mediante npx. Las sesiones web de ChatGPT y Claude solo en navegador no pueden iniciar un proceso stdio local directamente.

Cada fragmento a continuación usa ese par. Si tu tienda aún tiene un token ya preparado de una aplicación personalizada creada en el admin, reemplaza SHOPIFY_CLIENT_ID y SHOPIFY_CLIENT_SECRET con un solo SHOPIFY_ACCESS_TOKEN — consulta Obtener acceso.

codex mcp add shopify-admin \
  --env SHOPIFY_STORE_DOMAIN=my-store.myshopify.com \
  --env SHOPIFY_CLIENT_ID=your_client_id \
  --env SHOPIFY_CLIENT_SECRET=your_client_secret \
  -- npx -y mcp-shopify-admin@latest

codex mcp list

claude mcp add \
  --env SHOPIFY_STORE_DOMAIN=my-store.myshopify.com \
  --env SHOPIFY_CLIENT_ID=your_client_id \
  --env SHOPIFY_CLIENT_SECRET=your_client_secret \
  --transport stdio --scope user shopify-admin \
  -- npx -y mcp-shopify-admin@latest

claude mcp list

{
  "mcpServers": {
    "shopify-admin": {
      "command": "npx",
      "args": ["-y", "mcp-shopify-admin@latest"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "my-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

{
  "mcpServers": {
    "shopify-admin": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-shopify-admin@latest"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "my-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "shopify_store_domain",
      "description": "Shopify store domain, for example my-store.myshopify.com"
    },
    {
      "type": "promptString",
      "id": "shopify_client_id",
      "description": "Client ID of the Shopify Dev Dashboard app"
    },
    {
      "type": "promptString",
      "id": "shopify_client_secret",
      "description": "Client secret of that app",
      "password": true
    }
  ],
  "servers": {
    "shopify-admin": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-shopify-admin@latest"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "${input:shopify_store_domain}",
        "SHOPIFY_CLIENT_ID": "${input:shopify_client_id}",
        "SHOPIFY_CLIENT_SECRET": "${input:shopify_client_secret}"
      }
    }
  }
}

Qué puedes pedirle que haga

• Inspeccionar la tienda. Muestra detalles de la tienda, ubicaciones, productos, pedidos, clientes o descuentos.
• Trabajar con productos. Crea un borrador de producto, actualiza campos de producto o cambia precios de variantes.
• Rastrear inventario. Encuentra ubicaciones y establece la cantidad disponible absoluta para artículos de inventario.
• Revisar pedidos. Busca pedidos, inspecciona un pedido completo o cancela un pedido elegible con opciones explícitas de reembolso y reposición.
• Gestionar descuentos. Lista descuentos existentes o crea un descuento básico por código.
• Usar la vía de escape. Ejecuta un documento GraphQL de Admin arbitrario para capacidades que no tienen una herramienta dedicada.

Qué puede cambiar en Shopify

Este servidor no proporciona herramientas dedicadas para crear pedidos, cumplimiento, escrituras de clientes, creación de variantes, medios, descuentos dirigidos o publicar productos en canales de venta. Usa graphql_request solo cuando entiendas el documento y su respuesta userErrors.

El cliente de IA puede pedir confirmación antes de una escritura, pero el comportamiento de confirmación pertenece a ese cliente. Una solicitud clara de crear, actualizar, establecer o cancelar autoriza la operación correspondiente del servidor.

Obtener acceso

El servidor se autentica de una de dos maneras: con el ID de cliente y el secreto de una aplicación de Dev Dashboard, que intercambia por un token de acceso él mismo, o con un token de acceso de API de Admin listo para usar que envía tal cual. Si ambos están configurados, el token ya preparado gana.

Aplicación de Dev Dashboard (recomendado)

Shopify dejó de permitir nuevas aplicaciones personalizadas creadas en el admin el 2026-01-01, por lo que este es el camino para cualquier tienda que se configure hoy.

1. Crea una aplicación en el Shopify Dev Dashboard o con la Shopify CLI, en la misma organización de Shopify a la que pertenece la tienda.
2. Dale los alcances de acceso de API de Admin que necesites, como read_products, write_products, read_orders, read_customers, read_locations, write_inventory, read_discounts y write_discounts.
3. Instala la aplicación en la tienda.
4. Usa el ID de cliente y el secreto de cliente de la aplicación como SHOPIFY_CLIENT_ID y SHOPIFY_CLIENT_SECRET.

Desde allí, el servidor ejecuta la concesión de credenciales de cliente contra https://{store}.myshopify.com/admin/oauth/access_token por su cuenta. El token que Shopify devuelve vive 24 horas; el servidor lo mantiene solo en memoria — nunca en disco —, lo regenera poco antes de que expire, permite que las llamadas de herramientas paralelas compartan un intercambio y genera uno nuevo si la API responde 401. Nada que renovar a mano.

La concesión funciona solo cuando la aplicación y la tienda pertenecen a la misma organización de Shopify. De lo contrario, Shopify la rechaza con shop_not_permitted, y el servidor transmite eso como una pista que nombra el desajuste de organización. Reemitir las credenciales no ayuda: mueve la aplicación a la organización de la tienda, o usa una tienda de ella.

Aplicaciones personalizadas existentes creadas en el admin (heredado)

Las aplicaciones creadas en el admin de Shopify antes del 2026-01-01 siguen funcionando, y su token todavía se acepta. Si ya mantienes una:

1. Abre la aplicación en el admin de Shopify.
2. Confirma los alcances de acceso de API de Admin requeridos, como read_products, write_products, read_orders, read_customers, read_locations, write_inventory, read_discounts y write_discounts.
3. Instala o reinstala la aplicación si Shopify te pide generar credenciales.
4. Usa el token de acceso de API de Admin emitido como SHOPIFY_ACCESS_TOKEN.

El servidor envía este token tal cual y nunca lo renueva, por lo que reemplazarlo cuando deje de funcionar es tu responsabilidad. Consulta la documentación de aplicaciones personalizadas heredadas creadas en el admin de Shopify.

Trata el token de acceso y el secreto de cliente como contraseñas y nunca los confirmes en Git. Para pruebas seguras, usa una tienda de desarrollo de Shopify.

Configuración

* SHOPIFY_API_BASE puede reemplazar el dominio de la tienda para pruebas locales, pero una solicitud real de Shopify aún necesita credenciales.

** Se requiere una de las dos rutas de autenticación: SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET, o SHOPIFY_ACCESS_TOKEN. Con ninguna, el servidor aún se inicia y responde initialize, pero cada llamada de herramienta devuelve un error que nombra ambas opciones. Las variables se leen al inicio, así que reinicia el servidor después de cambiarlas.

Datos, límites y trabajo en segundo plano

• Cubo de costo de GraphQL. Cada resultado expone actualQueryCost, currentlyAvailable, maximumAvailable y restoreRate cuando Shopify los proporciona. Una página con first de hasta 250 suele ser más barata que muchas páginas pequeñas.
• Los reintentos son asimétricos. THROTTLED y HTTP 429 se reintentan con la espera que Shopify informa. Los errores 5xx y de red se reintentan solo para lecturas; las mutaciones no se reproducen después de esos fallos.
• Historial de pedidos. Los pedidos con más de 60 días requieren el alcance read_all_orders; sin él, Shopify no los devuelve.
• Sin monitoreo en segundo plano. El servidor funciona cuando se le llama. Si tu aplicación de IA admite tareas programadas, puede verificar pedidos o inventario periódicamente.
• Telemetría anónima. El servidor envía eventos técnicos de instalación y uso de herramientas sin secretos, datos de la tienda, argumentos ni indicaciones. Desactívalo para todos los servidores MCP de Ask Ads con ASKADS_TELEMETRY=0.

Documentación técnica

• Catálogo de capacidades — una página orientada a tareas para cada una de las 16 herramientas.
• Todas las herramientas y parámetros
• Guía de desarrollo
• Guía de publicación
• API GraphQL de Shopify Admin

Soporte

¿Encontraste un error o un escenario faltante? Crea un problema o contáctanos en Telegram.

¡Llegaste al final!