Shopify MCP Server

Servidor MCP Shopify para interagir com dados da loja Shopify via GraphQL, incluindo produtos, pedidos, clientes e fluxos de trabalho de e-commerce.

GitHub

Documentação

Shopify MCP Server

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 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çada de pedidos
Integração GraphQL: Integração direta com a API GraphQL Admin da 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
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 da variante, incluindo detalhes do produto
get-customers
- Obter clientes da 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 para etiquetar
  - 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 para ordenar por ('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 irão inserir
  - 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 rascunho
- Entradas:
  - lineItems (matriz): Matriz de itens com variantId e quantidade
  - email (string): Email do cliente
  - shippingAddress (objeto): Detalhes do endereço de envio
  - note (string opcional): Nota opcional para o pedido
- Retorna: Detalhes do pedido rascunho criado
complete-draft-order
- Concluir um pedido rascunho
- Entradas:
  - draftOrderId (string): ID do pedido rascunho a concluir
  - variantId (string): ID da variante no pedido 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 para 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 da Shopify

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

No admin da sua Shopify, vá para Configurações > Apps e canais de vendas
Clique em Desenvolver apps (talvez seja necessário ativar a pré-visualização 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 commitado no controle de versão. Mais detalhes sobre como criar um app da 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 da Shopify
zod - Validação de tipos em tempo de execução

Contribuindo

Contribuições são bem-vindas! Por favor, leia nossas Diretrizes de Contribuição primeiro.

Licença

MIT

Comunidade

Construído com ❤️ usando o Model Context Protocol