Freento MCP Server

O servidor Freento MCP conecta assistentes de IA a uma loja Magento 2 por meio do Model Context Protocol, permitindo acesso seguro a dados de produtos, clientes e pedidos através de uma API padronizada.

GitHub

Experimente este MCPPatrocinado

Documentação

Freento MCP para Magento 2 — Guia do Usuário

Conecte sua loja Magento 2 a assistentes de IA como Claude e ChatGPT usando o Model Context Protocol (MCP).

Visão Geral

Freento MCP é uma extensão do Magento 2 que implementa o Model Context Protocol — um padrão aberto para conectar assistentes de IA a fontes de dados externas. Com esta extensão, você pode:

Consultar pedidos, produtos, clientes e estoque usando linguagem natural
Gerar relatórios de vendas e análises em tempo real
Monitorar a saúde do sistema (versões de PHP, MySQL, cache, mecanismo de busca)
Auditar usuários administradores e configurações de segurança

Como funciona:

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  AI Assistant   │  HTTP   │  Freento MCP    │         │   Magento 2 /   │
│  (Claude/GPT)   │ ◄─────► │  Server         │ ◄─────► │Server Resources │
└─────────────────┘ JSON-RPC└─────────────────┘         └─────────────────┘

O servidor MCP atua como uma ponte segura entre assistentes de IA e sua instalação Magento, fornecendo acesso a diversos recursos da loja, incluindo banco de dados, configuração e outros subsistemas do Magento.

Requisitos

Magento 2.4.x (Open Source ou Commerce)
PHP 8.1 ou superior
Um cliente de IA compatível com MCP (Claude Code, Claude Desktop ou ChatGPT com plugin MCP)

Instalação

Via Composer (Recomendado)

composer require freento/module-mcp
php bin/magento module:enable Freento_Mcp
php bin/magento setup:upgrade
php bin/magento cache:flush

Instalação Manual

Baixe o módulo e extraia para app/code/Freento/Mcp/
Habilite o módulo:

php bin/magento module:enable Freento_Mcp
php bin/magento setup:upgrade
php bin/magento cache:flush

Verificar Instalação

php bin/magento module:status Freento_Mcp

Saída esperada: Module is enabled

Configuração

Etapa 1: Criar Função ACL

No Admin do Magento, vá para Sistema > Freento MCP > Regras ACL
Clique em Adicionar Nova Função
Insira um nome (ex.: "Assistente de IA")
Selecione quais ferramentas a função pode acessar:
- Ferramentas de vendas (pedidos, cotações, notas de crédito)
- Ferramentas de catálogo (produtos, estoque)
- Ferramentas de clientes
- Ferramentas de administração
- Ferramentas de sistema
Salve a função

Etapa 2: Criar Cliente OAuth

Vá para Sistema > Freento MCP > Clientes MCP de IA
Clique em Adicionar Novo Cliente
Insira um nome (ex.: "Claude Code")
Selecione a Função ACL criada na Etapa 1
Salve o cliente
Copie o Client ID e o Client Secret

Etapa 3: Gerar Token de Acesso

Abra o Cliente OAuth que você criou
Clique em Gerar OTP — copie a senha de uso único (válida por 24 horas)
Clique em Gerar Token — insira o OTP quando solicitado
Copie o Token de Acesso gerado

Claude Code

Adicione ao .mcp.json do seu projeto:

{
  "mcpServers": {
    "magento": {
      "type": "http",
      "url": "https://your-store.com/freento_mcp/index/index",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Em seguida, reconecte o MCP no Claude Code:

/mcp

Claude Desktop

Edite a configuração do Claude Desktop (~/.config/claude/claude_desktop_config.json no Linux/Mac ou %APPDATA%\Claude\claude_desktop_config.json no Windows):

{
  "mcpServers": {
    "magento": {
      "type": "http",
      "url": "https://your-store.com/freento_mcp/index/index",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Reinicie o Claude Desktop para aplicar as alterações.

ChatGPT e Outros Clientes Web

Para ferramentas de IA baseadas na web que suportam OAuth 2.0:

Registre o endpoint MCP da sua loja: https://your-store.com/freento_mcp/index/index
Insira o Client ID e o Client Secret da Etapa 2
Quando solicitado a autorizar, insira o OTP gerado na página do Cliente OAuth
Conclua o fluxo de autorização OAuth

Ferramentas Disponíveis

Cada ferramenta suporta filtragem flexível, ordenação e paginação. Combinadas com IA, essas capacidades se tornam praticamente ilimitadas — a IA pode executar múltiplas consultas, cruzar dados, agrupar e agregar resultados e fornecer análises inteligentes.

A IA pode:

Executar múltiplas consultas em diferentes entidades em uma única conversa
Filtrar por qualquer campo usando operadores: eq, neq, in, like, gt, gte, lt, lte
Ordenar e paginar resultados
Agregar com sum, count, avg, min, max
Agrupar por campo ou período de tempo (dia, mês)
Combinar e analisar dados de múltiplas fontes

Ferramentas de Vendas

Ferramenta	Descrição
`get_orders`	Consultar pedidos com filtragem, paginação e agregação
`get_order_items`	Obter itens de linha do pedido (produtos nos pedidos)
`get_quotes`	Consultar carrinhos de compras (ativos e abandonados)
`get_quote_items`	Obter itens de linha do carrinho
`get_creditmemos`	Consultar notas de crédito

Ferramentas de Marketing

Ferramenta	Descrição
`get_cart_price_rules`	Consultar regras de preço do carrinho
`get_coupons`	Consultar cupons

Ferramentas de Catálogo

Ferramenta	Descrição
`get_products`	Consultar produtos com filtragem por atributos
`get_categories`	Consultar categorias de produtos
`get_product_prices`	Obter preços de produtos por grupo de clientes e site
`get_product_tier_prices`	Obter regras de preço escalonado (descontos por quantidade)
`get_tax_rules`	Obter regras e alíquotas de impostos
`get_stock_single_stock`	Obter níveis de inventário/estoque

Ferramentas de Clientes

Ferramenta	Descrição
`get_customers`	Consultar contas de clientes

Ferramentas de Administração

Ferramenta	Descrição
`get_admins`	Listar usuários administradores e suas funções
`get_locked_admins`	Encontrar contas de administrador bloqueadas (tentativas de login falhas)

Ferramentas de Sistema

Ferramenta	Descrição
`get_system_versions`	Obter versões de Magento, PHP, MySQL, Redis, OpenSearch
`get_stores`	Obter hierarquia da loja (sites, grupos de lojas, visualizações de loja)

Exemplos de Uso

Após a configuração, você pode fazer perguntas ao seu assistente de IA em linguagem natural:

Pedidos e Vendas

"How many orders were placed last month?"
"Show me the 10 most recent orders"
"Find all orders over $500 that are still processing"
"What's the total revenue by payment method this year?"
"List orders for customer john@example.com"

Produtos e Estoque

"Show me out of stock products"
"Find products with SKU starting with 'ABC'"
"List products with less than 10 items in stock"
"Get all configurable products updated this week"

Clientes

"How many customers registered this month?"
"Find customer with email jane@example.com"
"List customers in the Wholesale group"

Sistema e Administração

"What PHP version is running?"
"Show me all admin users"
"Are there any locked admin accounts?"
"What search engine is configured?"

Análises e Relatórios

"Revenue by month for the last 12 months"
"Top 10 customers by total order value"
"Average order value by payment method"
"Order count by status"

Análise Avançada com IA

O verdadeiro poder vem da combinação de dados com raciocínio de IA. Faça perguntas de negócios complexas e obtenha insights acionáveis:

Inteligência de Clientes:

"Analyze my top 10 customers from the last 6 months. Who are they,
what do they buy, and how can I increase sales?"

A IA recuperará os dados e fornecerá análises como:

Mike Johnson — US$ 4.250 no total, 8 pedidos Perfil: Baterista profissional comprando pratos e baquetas a cada 5-6 semanas

Recomendação: Configure reabastecimento automático de baquetas, ofereça acesso antecipado a novas chegadas de pratos, considere um nível de "fidelidade do baterista" com desconto.

Prevenção de Churn:

"Find customers who were active but haven't ordered in 90 days.
What patterns do you see and how can I win them back?"

Otimização de Estoque:

"Analyze sales velocity vs current stock levels.
What should I reorder and what's at risk of becoming dead stock?"

Oportunidades de Receita:

"What patterns exist in high-value orders? How can I get more customers
to spend at that level?"

Análise de Carrinhos Abandonados:

"Look at abandoned carts from this week. What are people leaving behind
and what might be causing it?"

Isso transforma os dados da sua loja em inteligência de negócios estratégica — insights que normalmente exigiriam horas com planilhas ou um analista dedicado.

Filtros e Operadores

Todas as ferramentas de listagem suportam filtragem poderosa através do parâmetro filters.

Estrutura do Filtro

{
  "filters": {
    "field_name": { "operator": "value" }
  }
}

Operadores Disponíveis

Operador	Descrição	Exemplo
`eq`	Igual a	`{"status": {"eq": "processing"}}`
`neq`	Diferente de	`{"status": {"neq": "canceled"}}`
`in`	Na lista	`{"status": {"in": ["processing", "complete"]}}`
`nin`	Não na lista	`{"status": {"nin": ["canceled", "closed"]}}`
`like`	Padrão SQL LIKE	`{"email": {"like": "%@gmail.com"}}`
`nlike`	SQL NOT LIKE	`{"sku": {"nlike": "TEST%"}}`
`gt`	Maior que	`{"grand_total": {"gt": 100}}`
`gte`	Maior ou igual	`{"qty": {"gte": 10}}`
`lt`	Menor que	`{"created_at": {"lt": "2024-01-01"}}`
`lte`	Menor ou igual	`{"price": {"lte": 50}}`

Combinando Filtros

Múltiplos filtros são combinados com lógica AND:

{
  "filters": {
    "status": {"in": ["processing", "pending"]},
    "grand_total": {"gte": 100},
    "created_at": {"gte": "2024-01-01"}
  }
}

Filtragem por Data

Use o formato YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS:

{
  "filters": {
    "created_at": {"gte": "2024-01-01", "lt": "2024-02-01"}
  }
}

Agregação e Análises

A ferramenta get_orders suporta agregação para análises:

Parâmetros

Parâmetro	Valores	Descrição
`function`	`count`, `sum`, `avg`, `min`, `max`	Função de agregação
`field`	`grand_total`, `total_qty_ordered`, `total_item_count`	Campo a agregar
`group_by`	`status`, `month`, `day`, `customer_email`, `store_id`, `payment_method`	Agrupamento

Exemplos

Contagem total de pedidos:

{"function": "count"}

Receita por mês:

{
  "function": "sum",
  "field": "grand_total",
  "group_by": "month"
}

Valor médio do pedido por método de pagamento:

{
  "function": "avg",
  "field": "grand_total",
  "group_by": "payment_method"
}

Top 10 clientes por gastos:

{
  "function": "sum",
  "field": "grand_total",
  "group_by": "customer_email",
  "filters": {
    "status": {"nin": ["canceled", "closed"]}
  },
  "limit": 10
}

Solução de Problemas

Ferramentas não aparecem no assistente de IA

Verifique se o módulo está habilitado:

php bin/magento module:status Freento_Mcp

Limpe o cache do Magento:
```
php bin/magento cache:flush
```
Reconecte o MCP no seu cliente de IA (ex.: /mcp no Claude Code)

Erro "Falha na autenticação"

Verifique se o seu token de acesso está correto
Verifique se o Cliente OAuth está habilitado no Admin do Magento
Regere o token se ele expirou

Erro "Acesso negado"

A Função ACL não possui as permissões necessárias. Edite a Função ACL em Sistema > Freento MCP > Regras ACL e conceda acesso às ferramentas necessárias.

Tempo limite de conexão

Verifique se sua loja Magento está acessível pela internet
Verifique se as regras de firewall permitem conexões de entrada
Para desenvolvimento local, use um serviço de túnel como ngrok

Teste o endpoint manualmente

curl -X POST https://your-store.com/freento_mcp/index/index \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Segurança

Boas Práticas

Use HTTPS — Sempre use HTTPS em produção para criptografar as comunicações da API
Permissões Mínimas — Conceda apenas as ferramentas necessárias para o seu caso de uso através das Funções ACL
Clientes Separados — Crie Clientes OAuth separados para diferentes usuários/finalidades
Auditorias Regulares — Revise periodicamente os clientes ativos e desative os não utilizados
Rotação de Tokens — Regere os tokens de acesso periodicamente
Modo de Anonimato — Habilite o modo de anonimato em Stores > Configuration > Freento MCP > Privacy para ocultar campos de PII (e-mails, nomes) das respostas das ferramentas MCP. Como os assistentes de IA conectados via MCP são serviços de terceiros, é recomendado habilitar este modo para evitar que dados pessoais de clientes sejam transmitidos externamente, a menos que seja explicitamente necessário.

Segurança de Tokens

Nunca envie tokens para controle de versão
Use variáveis de ambiente ou gerenciamento seguro de segredos
Rote os tokens periodicamente
Revogue tokens imediatamente se comprometidos

Suporte

Contato: https://freento.com/contact

Licença

Licença MIT — veja LICENSE para detalhes.