mcp-shopify-admin

Shopify Admin MCP

English | Русский

A1 Shopify Admin MCP conecta aplicações de IA a uma loja Shopify por meio da Admin GraphQL API. Pergunte em linguagem natural sobre produtos, pedidos, clientes, inventário, descontos e dados da loja; o assistente usa as ferramentas prontas do servidor e mostra o resultado.

• Uma loja por servidor. O domínio da loja e as credenciais vêm da configuração; as ferramentas não podem alternar para outra loja.
• Tokens sempre atualizados. Dê ao servidor o client ID e o client secret de um app do Shopify Dev Dashboard e ele gera o token da Admin API por conta própria, mantém apenas em memória e o regenera antes da expiração de 24 horas. Um token pronto de um app customizado antigo também funciona.
• 16 ferramentas focadas. Leia dados da loja, produtos, pedidos, clientes, locais, inventário e descontos, além de criar ou atualizar os registros suportados.
• Falhas de GraphQL são expostas. O Shopify pode retornar HTTP 200 para uma mutação com falha, então o servidor verifica userErrors e rejeita respostas GraphQL vazias ou malformadas.
• Respostas conscientes de custo. Cada resultado inclui o bucket de custo do GraphQL: o custo da requisição e os pontos disponíveis para as próximas chamadas.
• Risco visível. Leituras são somente leitura; gravações de produto, preço, inventário e desconto são explícitas; cancelamento de pedido e GraphQL arbitrário são marcados como destrutivos.

Comece com uma solicitação somente leitura:

Mostre os pedidos mais recentes e os produtos que atualmente têm inventário.

Conecte o servidor · Explore casos de uso · Abra a documentação técnica

Veja funcionando em um minuto

Você: Mostre os pedidos mais recentes e os produtos que atualmente têm inventário.

Assistente: Mostra pedidos recentes com seus status e totais, depois produtos com preços e inventário. Nada é alterado.

Você: Prepare um código de desconto de 20% chamado SUMMER por duas semanas.

Assistente: Mostra o código proposto, porcentagem, datas e limites, e então pede confirmação antes de criá-lo.

Você: Confirmo.

Conteúdo

• Início rápido
• O que você pode pedir para ele fazer
• O que pode mudar no Shopify
• Obtendo acesso
• Configuração
• Dados, limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

Você precisa de Node.js 20+, um domínio de loja como my-store.myshopify.com e credenciais da Admin API. O conjunto recomendado é o client ID e o client secret de um app do Shopify Dev Dashboard: o servidor os troca por um token de acesso por conta própria e mantém esse token atualizado, o que importa porque o token emitido pelo Shopify para essa concessão expira após 24 horas. O app e a loja devem pertencer à mesma organização Shopify.

1. Obtenha acesso e prepare o client ID e o client secret do app.
2. Adicione o servidor MCP ao seu aplicativo de IA.
3. Envie a solicitação segura da seção de abertura.

O servidor roda localmente via stdio por meio de npx. Sessões web somente de navegador do ChatGPT e do Claude não podem iniciar um processo stdio local diretamente.

Cada trecho abaixo usa esse par. Se a sua loja ainda tiver um token pronto de um app customizado criado no admin, substitua SHOPIFY_CLIENT_ID e SHOPIFY_CLIENT_SECRET por um único SHOPIFY_ACCESS_TOKEN — veja Obtendo acesso.

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}"
      }
    }
  }
}

O que você pode pedir para ele fazer

• Inspecionar a loja. Mostre detalhes da loja, locais, produtos, pedidos, clientes ou descontos.
• Trabalhar com produtos. Crie um rascunho de produto, atualize campos de produto ou altere preços de variantes.
• Rastrear inventário. Encontre locais e defina a quantidade absoluta disponível para itens de inventário.
• Revisar pedidos. Pesquise pedidos, inspecione um pedido completo ou cancele um pedido elegível com escolhas explícitas de reembolso e reposição de estoque.
• Gerenciar descontos. Liste descontos existentes ou crie um desconto básico por código.
• Usar a saída de emergência. Execute um documento GraphQL Admin arbitrário para capacidades que não têm uma ferramenta dedicada.

O que pode mudar no Shopify

Este servidor não fornece ferramentas dedicadas para criar pedidos, atendimento (fulfillment), gravações de clientes, criação de variantes, mídia, descontos direcionados ou publicação de produtos em canais de venda. Use graphql_request somente quando você entender o documento e sua resposta userErrors.

O cliente de IA pode pedir confirmação antes de uma gravação, mas o comportamento de confirmação pertence a esse cliente. Uma solicitação clara para criar, atualizar, definir ou cancelar autoriza a operação correspondente do servidor.

Obtendo acesso

O servidor autentica de uma de duas maneiras: com o client ID e o client secret de um app do Dev Dashboard, que ele troca por um token de acesso por conta própria, ou com um token de acesso da Admin API pronto para uso, que ele envia como está. Se ambos estiverem configurados, o token pronto vence.

App do Dev Dashboard (recomendado)

O Shopify parou de permitir novos apps customizados criados no admin em 2026-01-01, então este é o caminho para qualquer loja configurada hoje.

1. Crie um app no Shopify Dev Dashboard ou com o Shopify CLI, na mesma organização Shopify à qual a loja pertence.
2. Dê a ele os escopos de acesso da Admin API que você precisa, como read_products, write_products, read_orders, read_customers, read_locations, write_inventory, read_discounts e write_discounts.
3. Instale o app na loja.
4. Use o client ID e o client secret do app como SHOPIFY_CLIENT_ID e SHOPIFY_CLIENT_SECRET.

A partir daí, o servidor executa a concessão de credenciais de cliente contra https://{store}.myshopify.com/admin/oauth/access_token por conta própria. O token que o Shopify retorna vive 24 horas; o servidor o mantém apenas em memória — nunca em disco —, o regenera pouco antes de expirar, permite que chamadas de ferramentas paralelas compartilhem uma única troca e gera um novo se a API responder com 401. Nada para renovar manualmente.

A concessão funciona somente quando o app e a loja pertencem à mesma organização Shopify. Caso contrário, o Shopify recusa com shop_not_permitted, e o servidor repassa isso como uma dica nomeando a incompatibilidade de organização. Reemitir as credenciais não ajuda: mova o app para a organização da loja ou use uma loja dela.

Apps customizados existentes criados no admin (legado)

Apps criados no admin do Shopify antes de 2026-01-01 continuam funcionando, e o token deles ainda é aceito. Se você já mantém um:

1. Abra o app no admin do Shopify.
2. Confirme os escopos de acesso da Admin API necessários, como read_products, write_products, read_orders, read_customers, read_locations, write_inventory, read_discounts e write_discounts.
3. Instale ou reinstale o app se o Shopify pedir para gerar credenciais.
4. Use o token de acesso da Admin API emitido como SHOPIFY_ACCESS_TOKEN.

O servidor envia esse token como está e nunca o atualiza, então substituí-lo quando parar de funcionar é responsabilidade sua. Veja a documentação de apps customizados legados criados no admin do Shopify.

Trate o token de acesso e o client secret como senhas e nunca os envie para o Git. Para testes seguros, use uma loja de desenvolvimento do Shopify.

Configuração

* SHOPIFY_API_BASE pode substituir o domínio da loja para testes locais, mas uma solicitação real ao Shopify ainda precisa de credenciais.

** Um dos dois caminhos de autenticação é obrigatório: SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET, ou SHOPIFY_ACCESS_TOKEN. Sem nenhum deles, o servidor ainda inicia e responde a initialize, mas toda chamada de ferramenta retorna um erro nomeando ambas as opções. As variáveis são lidas na inicialização, então reinicie o servidor após alterá-las.

Dados, limites e trabalho em segundo plano

• Faixa de custo GraphQL. Cada resultado expõe actualQueryCost, currentlyAvailable, maximumAvailable e restoreRate quando a Shopify os fornece. Uma página com first até 250 geralmente é mais barata do que muitas páginas pequenas.
• Repetições são assimétricas. THROTTLED e HTTP 429 são repetidos com o tempo de espera que a Shopify informa. Erros 5xx e de rede são repetidos apenas para leituras; mutações não são reproduzidas após essas falhas.
• Histórico de pedidos. Pedidos com mais de 60 dias exigem o escopo read_all_orders; sem ele, a Shopify não os retorna.
• Sem monitoramento em segundo plano. O servidor funciona quando é chamado. Se o seu aplicativo de IA suportar tarefas agendadas, ele pode verificar pedidos ou inventário periodicamente.
• Telemetria anônima. O servidor envia eventos técnicos de instalação e uso de ferramentas sem segredos, dados da loja, argumentos ou prompts. Desative isso para todos os servidores MCP do Ask Ads com ASKADS_TELEMETRY=0.

Documentação técnica

• Catálogo de capacidades — uma página orientada a tarefas para cada uma das 16 ferramentas.
• Todas as ferramentas e parâmetros
• Guia de desenvolvimento
• Guia de publicação
• API GraphQL do Shopify Admin

Suporte

Encontrou um bug ou cenário ausente? Crie um problema ou entre em contato conosco no Telegram.

Você chegou ao fim!