Freento MCP Server

El servidor Freento MCP conecta asistentes de IA a una tienda Magento 2 a través del Protocolo de Contexto de Modelo, permitiendo acceso seguro a productos, clientes y datos de pedidos mediante una API estandarizada.

GitHub

Prueba este MCPPatrocinado

Documentación

Freento MCP para Magento 2 — Guía de usuario

Conecta tu tienda Magento 2 a asistentes de IA como Claude y ChatGPT mediante el Protocolo de Contexto de Modelo (MCP).

Descripción general

Freento MCP es una extensión de Magento 2 que implementa el Protocolo de Contexto de Modelo, un estándar abierto para conectar asistentes de IA a fuentes de datos externas. Con esta extensión puedes:

Consultar pedidos, productos, clientes e inventario usando lenguaje natural
Generar informes de ventas y analíticas sobre la marcha
Supervisar el estado del sistema (versiones de PHP, MySQL, caché y motor de búsqueda)
Auditar usuarios administradores y ajustes de seguridad

Cómo funciona:

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

El servidor MCP actúa como un puente seguro entre los asistentes de IA y tu instalación de Magento, proporcionando acceso a diversos recursos de la tienda, incluidos la base de datos, la configuración y otros subsistemas de Magento.

Requisitos

Magento 2.4.x (Open Source o Commerce)
PHP 8.1 o superior
Un cliente de IA compatible con MCP (Claude Code, Claude Desktop o ChatGPT con el plugin MCP)

Instalación

Mediante Composer (recomendado)

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

Instalación manual

Descarga el módulo y extráelo en app/code/Freento/Mcp/
Habilita el módulo:

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

Verificar la instalación

php bin/magento module:status Freento_Mcp

Salida esperada: Module is enabled

Configuración

Paso 1: Crear un rol ACL

En el Administrador de Magento, ve a Sistema > Freento MCP > Reglas ACL
Haz clic en Agregar nuevo rol
Introduce un nombre (p. ej., "Asistente de IA")
Selecciona a qué herramientas puede acceder el rol:
- Herramientas de ventas (pedidos, presupuestos, notas de crédito)
- Herramientas de catálogo (productos, existencias)
- Herramientas de clientes
- Herramientas de administración
- Herramientas del sistema
Guarda el rol

Paso 2: Crear un cliente OAuth

Ve a Sistema > Freento MCP > Clientes MCP de IA
Haz clic en Agregar nuevo cliente
Introduce un nombre (p. ej., "Claude Code")
Selecciona el rol ACL creado en el Paso 1
Guarda el cliente
Copia el ID de cliente y el Secreto de cliente

Paso 3: Generar un token de acceso

Abre el cliente OAuth que creaste
Haz clic en Generar OTP — copia la contraseña de un solo uso (válida durante 24 horas)
Haz clic en Generar token — introduce el OTP cuando se te solicite
Copia el token de acceso generado

Claude Code

Añade a .mcp.json de tu proyecto:

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

Luego vuelve a conectar MCP en Claude Code:

/mcp

Claude Desktop

Edita la configuración de Claude Desktop (~/.config/claude/claude_desktop_config.json en Linux/Mac o %APPDATA%\Claude\claude_desktop_config.json en Windows):

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

Reinicia Claude Desktop para aplicar los cambios.

ChatGPT y otros clientes web

Para herramientas de IA basadas en web que admitan OAuth 2.0:

Registra el endpoint MCP de tu tienda: https://your-store.com/freento_mcp/index/index
Introduce el ID de cliente y el Secreto de cliente del Paso 2
Cuando se te solicite autorizar, introduce el OTP generado desde la página de Clientes OAuth
Completa el flujo de autorización OAuth

Herramientas disponibles

Cada herramienta admite filtrado, ordenación y paginación flexibles. Combinadas con IA, estas capacidades se vuelven prácticamente ilimitadas: la IA puede ejecutar múltiples consultas, cruzar datos, agrupar y agregar resultados, y proporcionar análisis inteligentes.

La IA puede:

Ejecutar múltiples consultas sobre distintas entidades en una sola conversación
Filtrar por cualquier campo usando operadores: eq, neq, in, like, gt, gte, lt, lte
Ordenar y paginar resultados
Agregar con sum, count, avg, min, max
Agrupar por campo o período de tiempo (día, mes)
Combinar y analizar datos de múltiples fuentes

Herramientas de ventas

Herramienta	Descripción
`get_orders`	Consulta pedidos con filtrado, paginación y agregación
`get_order_items`	Obtiene líneas de pedido (productos en pedidos)
`get_quotes`	Consulta carritos de compra (activos y abandonados)
`get_quote_items`	Obtiene líneas de carrito
`get_creditmemos`	Consulta notas de crédito

Herramientas de marketing

Herramienta	Descripción
`get_cart_price_rules`	Consulta reglas de precio de carrito
`get_coupons`	Consulta cupones

Herramientas de catálogo

Herramienta	Descripción
`get_products`	Consulta productos con filtrado por atributos
`get_categories`	Consulta categorías de productos
`get_product_prices`	Obtiene precios de productos por grupo de clientes y sitio web
`get_product_tier_prices`	Obtiene reglas de precio escalonado (descuentos por cantidad)
`get_tax_rules`	Obtiene reglas y tasas de impuestos
`get_stock_single_stock`	Obtiene niveles de inventario/existencias

Herramientas de clientes

Herramienta	Descripción
`get_customers`	Consulta cuentas de clientes

Herramientas de administración

Herramienta	Descripción
`get_admins`	Lista usuarios administradores y sus roles
`get_locked_admins`	Encuentra cuentas de administrador bloqueadas (intentos de inicio de sesión fallidos)

Herramientas del sistema

Herramienta	Descripción
`get_system_versions`	Obtiene versiones de Magento, PHP, MySQL, Redis y OpenSearch
`get_stores`	Obtiene la jerarquía de tiendas (sitios web, grupos de tiendas, vistas de tienda)

Ejemplos de uso

Una vez configurado, puedes hacer preguntas a tu asistente de IA en lenguaje natural:

Pedidos y ventas

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

Productos e inventario

"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 y administración

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

Analítica e informes

"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álisis avanzado impulsado por IA

El verdadero poder proviene de combinar datos con el razonamiento de la IA. Haz preguntas empresariales complejas y obtén información práctica:

Inteligencia 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?"

La IA recuperará los datos y proporcionará un análisis como:

Mike Johnson — $4,250 en total, 8 pedidos Perfil: baterista profesional que compra platillos y baquetas cada 5-6 semanas

Recomendación: configura el reabastecimiento automático de baquetas, ofrece acceso anticipado a las nuevas llegadas de platillos y considera un nivel de descuento por "fidelidad de baterista".

Prevención de abandono:

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

Optimización de inventario:

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

Oportunidades de ingresos:

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

Análisis de carritos abandonados:

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

Esto transforma los datos de tu tienda en inteligencia empresarial estratégica: información que normalmente requeriría horas con hojas de cálculo o un analista dedicado.

Filtrado y operadores

Todas las herramientas de listado admiten filtrado potente mediante el parámetro filters.

Estructura del filtro

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

Operadores disponibles

Operador	Descripción	Ejemplo
`eq`	Igual a	`{"status": {"eq": "processing"}}`
`neq`	Distinto de	`{"status": {"neq": "canceled"}}`
`in`	En la lista	`{"status": {"in": ["processing", "complete"]}}`
`nin`	No en la lista	`{"status": {"nin": ["canceled", "closed"]}}`
`like`	Patrón SQL LIKE	`{"email": {"like": "%@gmail.com"}}`
`nlike`	SQL NOT LIKE	`{"sku": {"nlike": "TEST%"}}`
`gt`	Mayor que	`{"grand_total": {"gt": 100}}`
`gte`	Mayor o igual que	`{"qty": {"gte": 10}}`
`lt`	Menor que	`{"created_at": {"lt": "2024-01-01"}}`
`lte`	Menor o igual que	`{"price": {"lte": 50}}`

Combinación de filtros

Múltiples filtros se combinan con lógica AND:

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

Filtrado por fecha

Usa el formato YYYY-MM-DD o YYYY-MM-DD HH:MM:SS:

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

Agregación y analítica

La herramienta get_orders admite agregación para analíticas:

Parámetros

Parámetro	Valores	Descripción
`function`	`count`, `sum`, `avg`, `min`, `max`	Función de agregación
`field`	`grand_total`, `total_qty_ordered`, `total_item_count`	Campo a agregar
`group_by`	`status`, `month`, `day`, `customer_email`, `store_id`, `payment_method`	Agrupación

Ejemplos

Número total de pedidos:

{"function": "count"}

Ingresos por mes:

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

Valor medio de pedido por método de pago:

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

Los 10 clientes principales por gasto:

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

Solución de problemas

Las herramientas no aparecen en el asistente de IA

Verifica que el módulo esté habilitado:

php bin/magento module:status Freento_Mcp

Vacía la caché de Magento:
```
php bin/magento cache:flush
```
Vuelve a conectar MCP en tu cliente de IA (p. ej., /mcp en Claude Code)

Error de "autenticación fallida"

Verifica que tu token de acceso sea correcto
Comprueba que el Cliente OAuth esté habilitado en el Administrador de Magento
Regenera el token si ha caducado

Error de "acceso denegado"

El rol ACL carece de los permisos necesarios. Edita el rol ACL en Sistema > Freento MCP > Reglas ACL y concede acceso a las herramientas necesarias.

Tiempo de espera agotado en la conexión

Verifica que tu tienda Magento sea accesible desde internet
Comprueba que las reglas del cortafuegos permitan conexiones entrantes
Para desarrollo local, usa un servicio de túnel como ngrok

Probar el 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"}'

Seguridad

Buenas prácticas

Usa HTTPS — Usa siempre HTTPS en producción para cifrar las comunicaciones de la API
Permisos mínimos — Concede solo las herramientas necesarias para tu caso de uso mediante roles ACL
Clientes separados — Crea clientes OAuth separados para distintos usuarios/fines
Auditorías periódicas — Revisa periódicamente los clientes activos y desactiva los que no se usen
Rotación de tokens — Regenera los tokens de acceso periódicamente
Modo de anonimato — Habilita el modo de anonimato en Stores > Configuration > Freento MCP > Privacy para ocultar campos de PII (correos electrónicos, nombres) de las respuestas de las herramientas MCP. Dado que los asistentes de IA que se conectan mediante MCP son servicios de terceros, se recomienda habilitar este modo para evitar que los datos personales de los clientes se transmitan externamente a menos que sea explícitamente necesario.

Seguridad de los tokens

Nunca subas tokens al control de versiones
Usa variables de entorno o gestión segura de secretos
Rota los tokens periódicamente
Revoca los tokens inmediatamente si se ven comprometidos

Soporte

Contacto: https://freento.com/contact

Licencia

Licencia MIT — consulta LICENSE para más detalles.