magento-mcp

MCP-Server, der einen Magento-2-Shop für KI-Assistenten bereitstellt über:

• REST-Admin-API — Katalog, Bestellungen, Kunden, CMS, Lagerbestand, Aktionen, Store-Konfiguration (Schreibwerkzeuge erfordern confirm: true), authentifiziert über OAuth 1.0a gegen eine Magento-Integration

• GraphQL — Storefront-förmige Katalogsuche, Produktdetails, Kategoriebaum

• Direktes schreibgeschütztes SQL — ein run_readonly_sql-Werkzeug plus vorgefertigte Analyseabfragen gegen die Live-Magento-Datenbank, optional über einen SSH-Tunnel erreichbar

Tools

Außerdem wird eine MCP-Ressource bereitgestellt: magento://store/config (Store-Konfiguration — Währungen, Gebietsschemata, Store-Ansichten, Basis-URLs).

Related MCP server: Shopify MCP

Setup

1. npm install

2. Kopieren Sie .env.example in .env und füllen Sie Folgendes aus:

   • MAGENTO_BASE_URL sowie OAuth-1.0a-Anmeldedaten von einer Magento-Integration (System → Erweiterungen → Integrationen → Neue Integration hinzufügen): MAGENTO_CONSUMER_KEY, MAGENTO_CONSUMER_SECRET, MAGENTO_ACCESS_TOKEN, MAGENTO_ACCESS_TOKEN_SECRET. Gewähren Sie der Integration nur die API-Ressourcen, die dieser Server tatsächlich benötigt — Magento zeigt Ihnen diese vier Werte nur einmal an, wenn Sie sie aktivieren. Dies umgeht die 2FA-Einschränkung, die die Passwort-Authentifizierung von Admin-Benutzern blockiert, und ist außerdem der Ansatz mit den geringsten Rechten.

   • MAGENTO_DB_* — muss auf einen MySQL-Benutzer mit ausschließlich SELECT-Berechtigungen verweisen:

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

     Erteilen Sie diesem Benutzer unter keinen Umständen INSERT/UPDATE/DELETE/DDL — die Abfrage-Schutzschicht auf Anwendungsebene (src/db/guard.ts) ist Defense in Depth, nicht die Sicherheitsgrenze.

3. npm run build

4. npm run test:connections — überprüft die REST-Authentifizierung, GraphQL und die DB-Verbindung anhand der Werte in .env, bevor der Server in einen Assistenten eingebunden wird. Siehe Lokale Entwicklung mit selbstsignierten Zertifikaten unten, falls dies bei TLS fehlschlägt.

5. Registrieren Sie bei Claude Desktop/Code, z. B. in 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": "..."
         }
       }
     }
   }

   Die MAGENTO_DB_SSH_*-Felder werden nur benötigt, wenn die DB-Verbindung über SSH getunnelt wird — lassen Sie sie vollständig weg (nicht nur leer), um wie zuvor direkt zu verbinden. Siehe „Erreichen einer entfernten/firewallgeschützten DB" unten.

Entwicklung

• npm run dev — direkt aus dem TS-Quellcode über tsx ausführen

• npm run typecheck

• npm test — Unit-Tests (src/db/guard.test.ts deckt die SQL-Sicherheitsvorkehrungen ab)

• npm run test:connections — Live-Smoke-Test der REST/GraphQL/DB-Erreichbarkeit gegen .env (kein Ersatz für npm test)

• npx @modelcontextprotocol/inspector node dist/index.js — interaktiv Werkzeuge auflisten/aufrufen

Lokale Entwicklung mit selbstsignierten Zertifikaten (mkcert, Warden usw.)

Das fetch von Node verwendet eine eigene gebündelte CA-Liste, getrennt vom Vertrauensspeicher Ihres Systems — selbst wenn curl und Ihr Browser ein lokal ausgestelltes mkcert-Zertifikat vertrauen, lehnt Node es mit UNABLE_TO_VERIFY_LEAF_SIGNATURE ab. Weisen Sie Node auf dieselbe Root-CA hin:

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

oder setzen Sie NODE_EXTRA_CA_CERTS in der Umgebung, mit der Ihr MCP-Client den Server startet (z. B. im env-Block in claude_desktop_config.json). Überprüfen Sie außerdem, dass MAGENTO_BASE_URL tatsächlich mit einem Hostnamen übereinstimmt, den das Zertifikat abdeckt (ERR_TLS_CERT_ALTNAME_INVALID bedeutet, dass dies nicht der Fall ist) — lokale Magento-Setups haben oft mehrere *.local/*.example.com-Hostnamen konfiguriert, und nur einer hat ein passendes Zertifikat.

Erreichen einer entfernten/firewallgeschützten DB (SSH-Tunnel)

MAGENTO_DB_HOST/PORT müssen sich nicht auf derselben Maschine wie dieser Server befinden — mysql2 verbindet sich einfach über TCP. Aber setzen Sie den MySQL-Port niemals dem offenen Internet aus, um das zu ermöglichen. Wenn die DB nicht bereits über ein privates Netzwerk/VPN erreichbar ist, setzen Sie MAGENTO_DB_SSH_* in .env (siehe .env.example für die vollständige Feldliste), um die DB-Verbindung stattdessen über SSH zu tunneln — dieser Server öffnet die SSH-Verbindung selbst (über das ssh2-Paket, nicht über einen externen ssh-Prozess) und leitet einen lokalen Port an MAGENTO_DB_HOST/PORT weiter, wie von der SSH-Host-Seite aufgelöst. Ein privater Schlüssel (MAGENTO_DB_SSH_PRIVATE_KEY_PATH) wird einem Passwort vorgezogen. Lassen Sie MAGENTO_DB_SSH_HOST ungesetzt, um wie zuvor direkt zu verbinden — der Tunnel ist opt-in und wird nur aktiviert, wenn diese Variable vorhanden ist.

Sicherheitshinweise

• Jedes zerstörerische REST-Werkzeug (update_product, delete_product, cancel_order, refund_order, update_customer, delete_customer, update_stock_item, set_config_value) zeigt eine Vorschau der Aktion und tut nichts, wenn es nicht mit confirm: true aufgerufen wird.

• run_readonly_sql akzeptiert nur eine einzelne SELECT-Anweisung, lehnt DML/DDL-Schlüsselwörter und sensible Tabellen (admin_user usw.) ab und fügt ein LIMIT ein/begrenzt es — siehe src/db/guard.ts. Dies kommt zusätzlich zu den SELECT-only-Berechtigungen des DB-Benutzers, nicht an deren Stelle.

• Abfrage-Timeout und Zeilenlimit sind über MAGENTO_DB_QUERY_TIMEOUT_MS / MAGENTO_DB_MAX_ROWS in .env konfigurierbar.