magento-mcp

Servidor MCP que expone una tienda Magento 2 a asistentes de IA mediante:

• REST Admin API — catálogo, pedidos, clientes, CMS, inventario, promociones, configuración de tienda (las herramientas de escritura requieren confirm: true), autenticado mediante OAuth 1.0a contra una integración de Magento

• GraphQL — búsqueda de catálogo orientada a la tienda, detalles de producto, árbol de categorías

• SQL directo de solo lectura — una herramienta run_readonly_sql más consultas de análisis predefinidas contra la base de datos de Magento en vivo, opcionalmente accesible a través de un túnel SSH

Herramientas

También expone un recurso MCP: magento://store/config (configuración de tienda — monedas, idiomas, vistas de tienda, URLs base).

Related MCP server: Shopify MCP

Configuración

1. npm install

2. Copia .env.example a .env y completa:

   • MAGENTO_BASE_URL más las credenciales OAuth 1.0a de una Integración de Magento (Sistema → Extensiones → Integraciones → Añadir nueva integración): MAGENTO_CONSUMER_KEY, MAGENTO_CONSUMER_SECRET, MAGENTO_ACCESS_TOKEN, MAGENTO_ACCESS_TOKEN_SECRET. Concede a la Integración solo los recursos de API que este servidor necesita realmente — Magento te muestra estos cuatro valores una sola vez, cuando la actives. Esto evita la restricción de 2FA que bloquea la autenticación con contraseña de usuario administrador y, además, es el enfoque de menor privilegio.

   • MAGENTO_DB_* — debe apuntar a un usuario de MySQL con permisos de solo SELECT:

     CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'change_me';
     GRANT SELECT ON magento_db.* TO 'mcp_readonly'@'%';
     FLUSH PRIVILEGES;

     No concedas a este usuario INSERT/UPDATE/DELETE/DDL bajo ninguna circunstancia — el guardián de consultas a nivel de aplicación (src/db/guard.ts) es defensa en profundidad, no el límite de seguridad.

3. npm run build

4. npm run test:connections — comprueba la autenticación REST, GraphQL y la conexión a la base de datos contra los valores de .env antes de conectar el servidor a un asistente. Consulta Desarrollo local con certificados autofirmados más abajo si esto falla con TLS.

5. Regístralo con Claude Desktop/Code, p. ej. en claude_desktop_config.json:

   {
     "mcpServers": {
       "magento": {
         "command": "node",
         "args": ["/var/www/html/magentoMCP/dist/index.js"],
         "env": {
           "MAGENTO_BASE_URL": "...",
           "MAGENTO_CONSUMER_KEY": "...",
           "MAGENTO_CONSUMER_SECRET": "...",
           "MAGENTO_ACCESS_TOKEN": "...",
           "MAGENTO_ACCESS_TOKEN_SECRET": "...",
           "MAGENTO_DB_HOST": "...",
           "MAGENTO_DB_NAME": "...",
           "MAGENTO_DB_READONLY_USER": "...",
           "MAGENTO_DB_READONLY_PASSWORD": "...",
           "MAGENTO_DB_SSH_HOST": "...",
           "MAGENTO_DB_SSH_USER": "...",
           "MAGENTO_DB_SSH_PRIVATE_KEY_PATH": "..."
         }
       }
     }
   }

   Los campos MAGENTO_DB_SSH_* solo son necesarios cuando se tuneliza la conexión a la base de datos a través de SSH — omítelos por completo (no solo déjalos en blanco) para conectar directamente, como antes. Consulta "Acceso a una base de datos remota/protegida por firewall" más abajo.

Desarrollo

• npm run dev — ejecuta directamente desde el código fuente TS mediante tsx

• npm run typecheck

• npm test — pruebas unitarias (src/db/guard.test.ts cubre las protecciones de seguridad de SQL)

• npm run test:connections — prueba de humo en vivo de la accesibilidad de REST/GraphQL/DB contra .env (no sustituye a npm test)

• npx @modelcontextprotocol/inspector node dist/index.js — lista/invoca herramientas de forma interactiva

Desarrollo local con certificados autofirmados (mkcert, Warden, etc.)

El fetch de Node usa su propia lista de CA incluida, separada del almacén de confianza de tu sistema — así que incluso si curl y tu navegador confían en un certificado mkcert emitido localmente, Node lo rechazará con UNABLE_TO_VERIFY_LEAF_SIGNATURE. Apunta Node a la misma CA raíz:

NODE_EXTRA_CA_CERTS=$(mkcert -CAROOT)/rootCA.pem npm run dev

o establece NODE_EXTRA_CA_CERTS en el entorno con el que tu cliente MCP lanza el servidor (p. ej. el bloque env en claude_desktop_config.json). También verifica que MAGENTO_BASE_URL realmente coincida con un nombre de host que cubra el certificado (ERR_TLS_CERT_ALTNAME_INVALID significa que no es así) — las instalaciones locales de Magento suelen tener varios nombres de host *.local/*.example.com configurados y solo uno tiene un certificado que coincida.

Acceso a una base de datos remota/protegida por firewall (túnel SSH)

MAGENTO_DB_HOST/PORT no necesitan estar en la misma máquina que este servidor — mysql2 simplemente se conecta a través de TCP. Pero nunca expongas el puerto de MySQL a Internet abierta para que eso funcione. Si la base de datos no es ya accesible a través de una red privada/VPN, establece MAGENTO_DB_SSH_* en .env (consulta .env.example para la lista completa de campos) para tunelizar la conexión a la base de datos a través de SSH en su lugar — este servidor abre la conexión SSH por sí mismo (mediante el paquete ssh2, no un proceso ssh externo) y reenvía un puerto local a MAGENTO_DB_HOST/PORT tal como se resuelve desde el lado del host SSH. Se prefiere una clave privada (MAGENTO_DB_SSH_PRIVATE_KEY_PATH) a una contraseña. Deja MAGENTO_DB_SSH_HOST sin establecer para conectar directamente, como antes — el túnel es opcional y solo se activa cuando esa variable está presente.

Notas de seguridad

• Toda herramienta REST destructiva (update_product, delete_product, cancel_order, refund_order, update_customer, delete_customer, update_stock_item, set_config_value) previsualiza la acción y no hace nada a menos que se llame con confirm: true.

• run_readonly_sql solo acepta una única sentencia SELECT, rechaza palabras clave DML/DDL y tablas sensibles (admin_user, etc.), e inyecta/limita un LIMIT — consulta src/db/guard.ts. Esto es además de, no en lugar de, los permisos de solo SELECT del usuario de la base de datos.

• El tiempo de espera de las consultas y el límite de filas son configurables mediante MAGENTO_DB_QUERY_TIMEOUT_MS / MAGENTO_DB_MAX_ROWS en .env.