Shopify MCP Server

Interaja com os dados da loja Shopify usando a API GraphQL.

Documentação

Shopify MCP Server

(por favor, deixe uma estrela se você gostar!)

Servidor MCP para a API da Shopify, permitindo interação com dados da loja através da API GraphQL. Este servidor fornece ferramentas para gerenciar produtos, clientes, pedidos e mais.

📦 Nome do Pacote: shopify-mcp 🚀 Comando: shopify-mcp (NÃO shopify-mcp-server)

Recursos

Gerenciamento de Produtos: CRUD completo para produtos, variantes e opções (8 ferramentas)
Gerenciamento de Clientes: CRUD completo, mesclagem e gerenciamento de endereços (8 ferramentas)
Gerenciamento de Pedidos: Busca inteligente, cancelamento, fechar/abrir, marcar como pago, atendimento, reembolsos (10 ferramentas)
Gerenciamento de Metacampos: Obter, definir e excluir metacampos em qualquer recurso (3 ferramentas)
Gerenciamento de Estoque: Definir quantidades absolutas de estoque em locais (1 ferramenta)
Gerenciamento de Etiquetas: Adicionar/remover etiquetas em qualquer recurso etiquetável (1 ferramenta)
Paginação e Ordenação: Paginação baseada em cursor e chaves de ordenação em todas as consultas de lista
Filtragem Avançada: Sintaxe de consulta Shopify pass-through para todos os endpoints de lista
Integração GraphQL: Integração direta com a API GraphQL Admin da Shopify (2026-01)
Tratamento Abrangente de Erros: Mensagens de erro claras para problemas de API e autenticação

Pré-requisitos

Node.js (versão 18 ou superior)
Uma loja Shopify com um aplicativo personalizado (veja as instruções de configuração abaixo)

Configuração

Autenticação

Este servidor suporta dois métodos de autenticação:

Opção 1: Credenciais de Cliente (aplicativos do Dev Dashboard, janeiro de 2026+)

A partir de 1º de janeiro de 2026, novos aplicativos Shopify são criados no Dev Dashboard e usam credenciais de cliente OAuth em vez de tokens de acesso estáticos.

No seu admin da Shopify, vá para Configurações > Aplicativos e canais de vendas
Clique em Desenvolver aplicativos > Criar aplicativo no painel de desenvolvimento
Crie um novo aplicativo e configure escopos da API Admin:
- read_products, write_products
- read_customers, write_customers
- read_orders, write_orders
Instale o aplicativo na sua loja
Copie seu ID do Cliente e Segredo do Cliente das credenciais da API do aplicativo

O servidor trocará automaticamente essas credenciais por um token de acesso e o renovará antes que expire (os tokens são válidos por ~24 horas).

Opção 2: Token de Acesso Estático (aplicativos legados)

Se você tiver um aplicativo personalizado existente com um token de acesso estático shpat_, ainda poderá usá-lo diretamente.

Uso com Claude Desktop

Credenciais 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 Acesso Estático (legado):

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

Locais para o arquivo de configuração do Claude Desktop:

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

Uso com Claude Code

Credenciais de Cliente:

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

Token de Acesso Estático (legado):

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

Alternativa: Executar Localmente com Variáveis de Ambiente

Se você preferir usar variáveis de ambiente em vez de argumentos de linha de comando:

Crie um arquivo .env com suas credenciais da Shopify:

Credenciais de Cliente:

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

Token de Acesso Estático (legado):

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

Execute o servidor com npx:
```
npx shopify-mcp
```

Instalação Direta (Opcional)

Se você quiser instalar o pacote globalmente:

npm install -g shopify-mcp

Então execute:

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

Opções Adicionais

--apiVersion: Especifique a versão da API da Shopify (padrão: 2026-01). Também pode ser definida via variável de ambiente SHOPIFY_API_VERSION.

⚠️ Importante: Se você vir erros sobre "a variável de ambiente SHOPIFY_ACCESS_TOKEN é necessária" ao usar argumentos de linha de comando, você pode ter um pacote diferente instalado. Certifique-se de estar usando shopify-mcp, não shopify-mcp-server.

Ferramentas Disponíveis (31)

Paginação, Ordenação e Filtragem

Todas as ferramentas de consulta de lista (get-products, get-customers, get-orders, get-customer-orders) suportam:

Paginação baseada em cursor: after / before (strings de cursor), com pageInfo na resposta (hasNextPage, hasPreviousPage, startCursor, endCursor)
Ordenação: sortKey (enum específico para cada recurso) e reverse (booleano)
Filtragem avançada: parâmetro query ou searchQuery aceitando sintaxe de consulta da Shopify

Gerenciamento de Produtos (8 ferramentas)

get-products
- Obter todos os produtos ou pesquisar por título com paginação e ordenação
- Entradas:
  - searchTitle (string, opcional): Filtrar produtos por título (envolve em title:*...*)
  - limit (número, padrão: 10): Número máximo de produtos a retornar
  - query (string, opcional): String de consulta Shopify bruta (ex.: "status:active vendor:Nike tag:sale")
  - sortKey (string, opcional): Um de CREATED_AT, ID, INVENTORY_TOTAL, PRODUCT_TYPE, PUBLISHED_AT, RELEVANCE, TITLE, UPDATED_AT, VENDOR
  - reverse (booleano, opcional): Inverter a ordem de classificação
  - after / before (string, opcional): Cursores de paginação
get-product-by-id
- Obter um produto específico por ID com detalhes completos, incluindo SEO, opções, mídia, variantes e coleções
- Entradas:
  - productId (string, obrigatório): GID do produto Shopify
- Retorna: productType, descriptionHtml, seo, options (com optionValues), media (imagens), variants, collections, tags, vendor, faixa de preço, estoque
create-product
- Criar um novo produto. Ao usar productOptions, a Shopify registra todos os valores de opção, mas cria apenas uma variante padrão (primeiro valor de cada opção, preço $0). Use manage-product-variants com strategy: REMOVE_STANDALONE_VARIANT depois para criar todas as variantes reais com preços.
- Entradas:
  - title (string, obrigatório): Título do produto
  - descriptionHtml (string, opcional): Descrição com HTML
  - handle (string, opcional): Slug de URL. Gerado automaticamente a partir do título se omitido
  - vendor (string, opcional): Fornecedor do produto
  - productType (string, opcional): Tipo do produto
  - tags (array de strings, opcional): Etiquetas do produto
  - status (string, opcional): "ACTIVE", "DRAFT" ou "ARCHIVED". Padrão "DRAFT"
  - seo (objeto, opcional): { title, description } para mecanismos de busca
  - metafields (array de objetos, opcional): Metacampos personalizados (namespace, key, value, type)
  - productOptions (array de objetos, opcional): Opções para criar inline, ex.: [{ name: "Size", values: [{ name: "S" }, { name: "M" }] }]. Máximo de 3 opções.
  - collectionsToJoin (array de strings, opcional): GIDs de coleções para adicionar o produto
update-product
- Atualizar os campos de um produto existente
- Entradas:
  - id (string, obrigatório): GID do produto Shopify
  - title (string, opcional): Novo título
  - descriptionHtml (string, opcional): Nova descrição
  - handle (string, opcional): Novo slug de URL
  - vendor (string, opcional): Novo fornecedor
  - productType (string, opcional): Novo tipo de produto
  - tags (array de strings, opcional): Novas etiquetas (substitui as existentes)
  - status (string, opcional): "ACTIVE", "DRAFT" ou "ARCHIVED"
  - seo (objeto, opcional): { title, description } para mecanismos de busca
  - metafields (array de objetos, opcional): Metacampos para definir ou atualizar
  - collectionsToJoin (array de strings, opcional): GIDs de coleções para adicionar o produto
  - collectionsToLeave (array de strings, opcional): GIDs de coleções para remover o produto
  - redirectNewHandle (booleano, opcional): Se verdadeiro, o handle antigo redireciona para o novo handle
delete-product
- Excluir um produto
- Entradas:
  - id (string, obrigatório): GID do produto Shopify
manage-product-options
- Criar, atualizar ou excluir opções de produto (ex.: Tamanho, Cor)
- Entradas:
  - productId (string, obrigatório): GID do produto Shopify
  - action (string, obrigatório): "create", "update" ou "delete"
  - variantStrategy (string, opcional): "LEAVE_AS_IS" (padrão) ou "CREATE" — controla se novas combinações de variantes são geradas ao adicionar opções
  - Para action: "create":
    - options (array, obrigatório): Opções para criar, ex.: [{ name: "Size", values: ["S", "M", "L"] }]
  - Para action: "update":
    - optionId (string, obrigatório): GID da opção para atualizar
    - name (string, opcional): Novo nome para a opção
    - position (número, opcional): Nova posição
    - valuesToAdd (array de strings, opcional): Valores para adicionar
    - valuesToDelete (array de strings, opcional): GIDs de valores para remover
  - Para action: "delete":
    - optionIds (array de strings, obrigatório): GIDs de opções para excluir
manage-product-variants
- Criar ou atualizar variantes de produto em massa
- Entradas:
  - productId (string, obrigatório): GID do produto Shopify
  - strategy (string, opcional): Como lidar com a variante padrão ao criar. "DEFAULT" (remove "Título Padrão" automaticamente), "REMOVE_STANDALONE_VARIANT" (recomendado para controle total) ou "PRESERVE_STANDALONE_VARIANT"
  - variants (array, obrigatório): Variantes para criar ou atualizar. Cada variante:
    - id (string, opcional): GID da variante para atualizações. Omita para criar nova
    - price (string, opcional): Preço, ex.: "49.00"
    - compareAtPrice (string, opcional): Preço comparativo para exibir descontos
    - sku (string, opcional): SKU (mapeado para inventoryItem.sku)
    - tracked (booleano, opcional): Se o estoque é rastreado. Defina false para impressão sob demanda
    - taxable (booleano, opcional): Se a variante é tributável
    - barcode (string, opcional): Código de barras
    - weight (número, opcional): Peso da variante
    - weightUnit (string, opcional): "GRAMS", "KILOGRAMS", "OUNCES" ou "POUNDS"
    - optionValues (array, opcional): Valores de opção, ex.: [{ optionName: "Size", name: "A4" }]
delete-product-variants
- Excluir uma ou mais variantes de um produto
- Entradas:
  - productId (string, obrigatório): GID do produto Shopify
  - variantIds (array de strings, obrigatório): GIDs de variantes para excluir

Gerenciamento de Clientes (8 ferramentas)

get-customers
- Listar clientes com busca, paginação e ordenação
- Entradas:
  - searchQuery (string, opcional): Texto livre ou sintaxe de consulta Shopify (ex.: "country:US tag:vip orders_count:>5")
  - limit (número, padrão: 10): Número máximo de clientes a retornar
  - sortKey (string, opcional): Um de CREATED_AT, ID, LAST_UPDATE, LOCATION, NAME, ORDERS_COUNT, RELEVANCE, TOTAL_SPENT, UPDATED_AT
  - reverse (booleano, opcional): Inverter a ordem de classificação
  - after / before (string, opcional): Cursores de paginação
get-customer-by-id
- Obter um único cliente por ID com detalhes completos
- Entradas:
  - id (string, obrigatório): ID do cliente Shopify (somente numérico, ex.: "6276879810626")
- Retorna: nome, e-mail, telefone, endereços, etiquetas, nota, status fiscal, valor gasto, contagem de pedidos, metacampos
create-customer

Criar um novo cliente
- Entradas:
  - firstName (string, opcional): Primeiro nome do cliente
  - lastName (string, opcional): Sobrenome do cliente
  - email (string, opcional): Endereço de e-mail do cliente
  - phone (string, opcional): Número de telefone do cliente
  - tags (array de strings, opcional): Tags a aplicar
  - note (string, opcional): Nota sobre o cliente
  - taxExempt (booleano, opcional): Se o cliente está isento de impostos
  - metafields (array de objetos, opcional): Metafields personalizados (namespace, key, value, type)
  - addresses (array de objetos, opcional): Endereços do cliente (address1, address2, city, provinceCode, zip, country, phone)

update-customer
- Atualizar as informações de um cliente
- Entradas:
  - id (string, obrigatório): ID do cliente Shopify (somente numérico, ex.: "6276879810626")
  - firstName (string, opcional): Primeiro nome do cliente
  - lastName (string, opcional): Sobrenome do cliente
  - email (string, opcional): Endereço de e-mail do cliente
  - phone (string, opcional): Número de telefone do cliente
  - tags (array de strings, opcional): Tags a aplicar ao cliente
  - note (string, opcional): Nota sobre o cliente
  - taxExempt (booleano, opcional): Se o cliente está isento de impostos
  - emailMarketingConsent (objeto, opcional): Configurações de consentimento de marketing por e-mail
    - marketingState (string, obrigatório): "NOT_SUBSCRIBED", "SUBSCRIBED", "UNSUBSCRIBED" ou "PENDING"
    - consentUpdatedAt (string, opcional): Timestamp ISO 8601
    - marketingOptInLevel (string, opcional): "SINGLE_OPT_IN", "CONFIRMED_OPT_IN" ou "UNKNOWN"
  - metafields (array de objetos, opcional): Metafields do cliente
delete-customer
- Excluir um cliente
- Entradas:
  - id (string, obrigatório): ID do cliente Shopify (somente numérico, ex.: "6276879810626")
customer-merge
- Mesclar dois registros de cliente em um só
- Entradas:
  - customerOneId (string, obrigatório): GID do primeiro cliente
  - customerTwoId (string, obrigatório): GID do segundo cliente
  - overrideFields (objeto, opcional): Substituir quais campos manter de qual cliente (firstName, lastName, email, phone, defaultAddress, note, tags)
manage-customer-address
- Criar, atualizar ou excluir o endereço de correspondência de um cliente
- Entradas:
  - customerId (string, obrigatório): GID do cliente
  - action (string, obrigatório): "create", "update" ou "delete"
  - addressId (string, opcional): GID do endereço (obrigatório para atualização/exclusão)
  - address (objeto, opcional): Campos do endereço (obrigatório para criação/atualização): address1, address2, city, company, countryCode, firstName, lastName, phone, provinceCode, zip
  - setAsDefault (booleano, opcional): Definir como endereço padrão do cliente

Gerenciamento de Pedidos (10 ferramentas)

get-orders
- Obter pedidos com filtragem, paginação e ordenação
- Entradas:
  - status (string, opcional): "any", "open", "closed" ou "cancelled". Padrão "any"
  - limit (número, padrão: 10): Número máximo de pedidos a retornar
  - query (string, opcional): String de consulta Shopify bruta (ex.: "financial_status:paid fulfillment_status:shipped tag:rush")
  - sortKey (string, opcional): Um de CREATED_AT, ORDER_NUMBER, TOTAL_PRICE, FINANCIAL_STATUS, FULFILLMENT_STATUS, UPDATED_AT, CUSTOMER_NAME, PROCESSED_AT, ID, RELEVANCE
  - reverse (booleano, opcional): Inverter a ordem de classificação
  - after / before (string, opcional): Cursores de paginação
get-order-by-id
- Obter um pedido específico por ID com busca inteligente — aceita nome do pedido (#77235 ou 77235), ID numérico (8054938337547) ou GID completo (gid://shopify/Order/...)
- Entradas:
  - orderId (string, obrigatório): Nome do pedido, ID numérico ou GID completo
- Retorna: preço, cliente, endereços de envio/cobrança, itens de linha, tags, notas, metafields, motivo de cancelamento, status de devolução, códigos de desconto, número de PO, timestamps
update-order
- Atualizar um pedido existente
- Entradas:
  - id (string, obrigatório): GID do pedido Shopify
  - tags (array de strings, opcional): Novas tags para o pedido
  - email (string, opcional): Atualizar o e-mail do cliente no pedido
  - note (string, opcional): Notas do pedido
  - phone (string, opcional): Número de telefone do pedido
  - poNumber (string, opcional): Número de ordem de compra
  - customAttributes (array de objetos, opcional): Atributos personalizados de chave-valor
  - metafields (array de objetos, opcional): Metafields do pedido
  - shippingAddress (objeto, opcional): Campos do endereço de envio
get-customer-orders
- Obter pedidos de um cliente específico com paginação e ordenação
- Entradas:
  - customerId (string, obrigatório): ID do cliente Shopify (somente numérico, ex.: "6276879810626")
  - limit (número, padrão: 10): Número máximo de pedidos a retornar
  - sortKey (string, opcional): Mesmas chaves de classificação que get-orders
  - reverse (booleano, opcional): Inverter a ordem de classificação
  - after / before (string, opcional): Cursores de paginação
order-cancel
- Cancelar um pedido com opções de reembolso, reposição de estoque e notificação ao cliente. Irreversível.
- Entradas:
  - orderId (string, obrigatório): GID do pedido
  - reason (string, obrigatório): "CUSTOMER", "DECLINED", "FRAUD", "INVENTORY", "OTHER" ou "STAFF"
  - restock (booleano, obrigatório): Se deve repor o estoque
  - notifyCustomer (booleano, padrão: false): Notificar o cliente
  - staffNote (string, opcional): Nota interna
  - refund (booleano, opcional): Reembolsar para o método de pagamento original
order-close-open
- Fechar ou reabrir um pedido
- Entradas:
  - orderId (string, obrigatório): GID do pedido
  - action (string, obrigatório): "close" ou "open"
order-mark-as-paid
- Marcar um pedido como pago (para pagamentos manuais/offline)
- Entradas:
  - orderId (string, obrigatório): GID do pedido
create-fulfillment
- Criar um atendimento (marcar itens como enviados) com rastreamento opcional
- Entradas:
  - lineItemsByFulfillmentOrder (array, obrigatório): Pedidos de atendimento e itens de linha a atender
  - trackingInfo (objeto, opcional): { number, url, company } detalhes de rastreamento
  - notifyCustomer (booleano, padrão: false): Enviar notificação de envio
refund-create
- Criar um reembolso total ou parcial com reposição de estoque opcional
- Entradas:
  - orderId (string, obrigatório): GID do pedido
  - refundLineItems (array, opcional): Itens de linha a reembolsar com lineItemId, quantity, restockType (CANCEL/RETURN/NO_RESTOCK), locationId
  - shipping (objeto, opcional): { amount, fullRefund } reembolso de envio
  - note (string, opcional): Nota de reembolso
  - notify (booleano, opcional): Enviar notificação de reembolso
create-draft-order
- Criar um pedido de rascunho para vendas por telefone/chat, faturamento ou atacado
- Entradas:
  - lineItems (array, obrigatório): Variantes de produto (variantId) ou itens personalizados (title + preço). Máx. 499
  - customerId (string, opcional): GID do cliente
  - email, phone, note, tags, poNumber (opcional)
  - shippingAddress, billingAddress (objetos, opcional)
  - appliedDiscount (objeto, opcional): { title, value, valueType } desconto no nível do pedido

Gerenciamento de Pedidos de Rascunho (1 ferramenta)

complete-draft-order
- Concluir um pedido de rascunho, convertendo-o em um pedido real
- Entradas:
  - draftOrderId (string, obrigatório): GID do pedido de rascunho
  - paymentGatewayId (string, opcional): GID do gateway de pagamento

Gerenciamento de Metafields (3 ferramentas)

get-metafields
- Obter metafields de qualquer recurso Shopify (produtos, pedidos, clientes, variantes, coleções, etc.)
- Entradas:
  - ownerId (string, obrigatório): GID de qualquer recurso
  - namespace (string, opcional): Filtrar por namespace
  - first (número, padrão: 25): Número de metafields a retornar
  - after (string, opcional): Cursor de paginação
set-metafields
- Definir metafields em qualquer recurso Shopify. Cria ou atualiza até 25 metafields atomicamente
- Entradas:
  - metafields (array, obrigatório): Metafields a definir, cada um com ownerId, key, value e opcional namespace, type
delete-metafields
- Excluir metafields de qualquer recurso Shopify
- Entradas:
  - metafields (array, obrigatório): Metafields a excluir, cada um com ownerId, namespace, key

Gerenciamento de Estoque (1 ferramenta)

inventory-set-quantities
- Definir quantidades absolutas de estoque para itens em locais específicos
- Entradas:
  - reason (string, obrigatório): Motivo da alteração (ex.: "correction", "cycle_count_available")
  - name (string, obrigatório): "available" ou "on_hand"
  - quantities (array, obrigatório): Itens com inventoryItemId, locationId, quantity

Gerenciamento de Tags (1 ferramenta)

manage-tags
- Adicionar ou remover tags em qualquer recurso com tags (pedidos, produtos, clientes, pedidos de rascunho, artigos)
- Entradas:
  - id (string, obrigatório): GID do recurso
  - tags (array de strings, obrigatório): Tags a adicionar ou remover
  - action (string, obrigatório): "add" ou "remove"

Referência de Filtros de Consulta de Pedidos

O parâmetro query da ferramenta get-orders suporta sintaxe de pesquisa do Shopify:

Filtro	Exemplo
`name`	`name:#77235`
`created_at`	`created_at:>2024-01-01` ou `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`

Depuração

Se você encontrar problemas, verifique os logs MCP do Claude Desktop:

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

Licença

MIT