Shopify MCP Server

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

Documentação

Shopify MCP Server

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

Recursos

Gerenciamento de Produtos: Pesquisar e recuperar informações de produtos
Gerenciamento de Clientes: Carregar dados de clientes e gerenciar tags de clientes
Gerenciamento de Pedidos: Consulta e filtragem avançadas de pedidos
Integração GraphQL: Integração direta com a API GraphQL Admin do Shopify
Tratamento Abrangente de Erros: Mensagens de erro claras para problemas de API e autenticação

Ferramentas

get-products
- Obter todos os produtos ou pesquisar por título
- Entradas:
  - searchTitle (string opcional): Filtrar produtos por título
  - limit (número): Número máximo de produtos a retornar
- Retorna: Detalhes formatados do produto, incluindo título, descrição, handle e variantes
get-products-by-collection
- Obter produtos de uma coleção específica
- Entradas:
  - collectionId (string): ID da coleção da qual obter produtos
  - limit (número opcional, padrão: 10): Número máximo de produtos a retornar
- Retorna: Detalhes formatados dos produtos da coleção especificada
get-products-by-ids
- Obter produtos pelos seus IDs
- Entradas:
  - productIds (matriz de strings): Matriz de IDs de produtos a recuperar
- Retorna: Detalhes formatados dos produtos especificados
update-product-price
- Atualizar preços de produtos pelo ID
- Entradas:
  - productId (string): ID do produto a atualizar
  - price (string): Novo preço do produto
- Retorna: Resposta da atualização
get-variants-by-ids
- Obter variantes de produtos pelos seus IDs
- Entradas:
  - variantIds (matriz de strings): Matriz de IDs de variantes a recuperar
- Retorna: Informações detalhadas das variantes, incluindo detalhes do produto
get-customers
- Obter clientes do Shopify com suporte a paginação
- Entradas:
  - limit (número opcional): Número máximo de clientes a retornar
  - next (string opcional): Cursor da próxima página
- Retorna: Dados do cliente em formato JSON
tag-customer
- Adicionar tags a um cliente
- Entradas:
  - customerId (string): ID do cliente a ser marcado
  - tags (matriz de strings): Tags a adicionar ao cliente
- Retorna: Mensagem de sucesso ou falha
get-orders
- Obter pedidos com filtragem e ordenação avançadas
- Entradas:
  - first (número opcional): Limite de pedidos a retornar
  - after (string opcional): Cursor da próxima página
  - query (string opcional): Filtrar pedidos usando sintaxe de consulta
  - sortKey (enum opcional): Campo pelo qual ordenar ('PROCESSED_AT', 'TOTAL_PRICE', 'ID', 'CREATED_AT', 'UPDATED_AT', 'ORDER_NUMBER')
  - reverse (booleano opcional): Inverter ordem de classificação
- Retorna: Detalhes formatados do pedido
get-order
- Obter um único pedido por ID
- Entradas:
  - orderId (string): ID do pedido a recuperar
- Retorna: Informações detalhadas do pedido
create-discount
- Criar um código de desconto básico
- Entradas:
  - title (string): Título do desconto
  - code (string): Código de desconto que os clientes inserirão
  - valueType (enum): Tipo de desconto ('percentage' ou 'fixed_amount')
  - value (número): Valor do desconto (percentual como decimal ou valor fixo)
  - startsAt (string): Data de início no formato ISO
  - endsAt (string opcional): Data de término opcional no formato ISO
  - appliesOncePerCustomer (booleano): Se o desconto pode ser usado apenas uma vez por cliente
- Retorna: Detalhes do desconto criado
create-draft-order
- Criar um pedido de rascunho
- Entradas:
  - lineItems (matriz): Matriz de itens com variantId e quantidade
  - email (string): E-mail do cliente
  - shippingAddress (objeto): Detalhes do endereço de envio
  - note (string opcional): Nota opcional para o pedido
- Retorna: Detalhes do pedido de rascunho criado
complete-draft-order
- Concluir um pedido de rascunho
- Entradas:
  - draftOrderId (string): ID do pedido de rascunho a concluir
  - variantId (string): ID da variante no pedido de rascunho
- Retorna: Detalhes do pedido concluído
get-collections
- Obter todas as coleções
- Entradas:
  - limit (número opcional, padrão: 10): Número máximo de coleções a retornar
  - name (string opcional): Filtrar coleções por nome
- Retorna: Detalhes da coleção
get-shop
- Obter detalhes da loja
- Entradas: Nenhuma
- Retorna: Informações básicas da loja
get-shop-details
- Obter detalhes estendidos da loja, incluindo países de envio
- Entradas: Nenhuma
- Retorna: Informações estendidas da loja, incluindo países de envio
manage-webhook
- Assinar, encontrar ou cancelar assinatura de webhooks
- Entradas:
  - action (enum): Ação a executar ('subscribe', 'find', 'unsubscribe')
  - callbackUrl (string): URL de callback do webhook
  - topic (enum): Tópico do webhook ao qual assinar
  - webhookId (string opcional): ID do webhook (obrigatório para cancelar assinatura)
- Retorna: Detalhes do webhook ou mensagem de sucesso

Configuração

Token de Acesso do Shopify

Para usar este servidor MCP, você precisará criar um aplicativo personalizado na sua loja Shopify:

No admin do Shopify, vá para Configurações > Apps e canais de vendas
Clique em Desenvolver apps (talvez seja necessário ativar a prévia do desenvolvedor primeiro)
Clique em Criar um app
Defina um nome para o seu app (por exemplo, "Shopify MCP Server")
Clique em Configurar escopos da API Admin
Selecione os seguintes escopos:
- read_products, write_products
- read_customers, write_customers
- read_orders, write_orders
Clique em Salvar
Clique em Instalar app
Clique em Instalar para dar ao app acesso aos dados da sua loja
Após a instalação, você verá seu token de acesso da API Admin
Copie este token - você precisará dele para a configuração

Nota: Armazene seu token de acesso com segurança. Ele fornece acesso aos dados da sua loja e nunca deve ser compartilhado ou enviado ao controle de versão. Mais detalhes sobre como criar um app Shopify podem ser encontrados aqui.

Uso com Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["-y", "shopify-mcp-server"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>",
        "MYSHOPIFY_DOMAIN": "<YOUR_SHOP>.myshopify.com"
      }
    }
  }
}

Desenvolvimento

Clone o repositório
Instale as dependências:

npm install

Crie um arquivo .env:

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

Compile o projeto:

npm run build

Execute os testes:

npm test

Dependências

@modelcontextprotocol/sdk - Implementação do protocolo MCP
graphql-request - Cliente GraphQL para a API do Shopify
zod - Validação de tipos em tempo de execução

Contribuição

Contribuições são bem-vindas! Leia nossas Diretrizes de Contribuição primeiro.

Licença

MIT

Comunidade

Feito com ❤️ usando o Model Context Protocol