MCP-Server für MySQL basierend auf NodeJS

Ein Model Context Protocol-Server, der Zugriff auf MySQL-Datenbanken bietet. Dieser Server ermöglicht LLMs die Überprüfung von Datenbankschemata und die Ausführung von SQL-Abfragen.

Inhaltsverzeichnis

• Anforderungen

• Installation

  • Schmiedekunst

  • In lokales Repository klonen

• Komponenten

• Konfiguration

• Umgebungsvariablen

• Multi-DB-Modus

• Schemaspezifische Berechtigungen

• Testen

• Fehlerbehebung

• Beitragen

• Lizenz

Anforderungen

• Node.js v18 oder höher

• MySQL 5.7 oder höher (MySQL 8.0+ empfohlen)

• MySQL-Benutzer mit entsprechenden Berechtigungen für die von Ihnen benötigten Vorgänge

• Für Schreibvorgänge: MySQL-Benutzer mit INSERT-, UPDATE- und/oder DELETE-Berechtigungen

Installation

Es gibt mehrere Möglichkeiten, den MCP-Server zu installieren und zu konfigurieren. Am häufigsten wird jedoch die folgende Website aufgerufen : https://smithery.ai/server/@benborla29/mcp-server-mysql

Cursor

Für Cursor IDE können Sie diesen MCP-Server mit dem folgenden Befehl in Ihrem Projekt installieren:

1. Besuchen Sie https://smithery.ai/server/@benborla29/mcp-server-mysql

2. Folgen Sie den Anweisungen für den Cursor

MCP Get bietet ein zentrales Register von MCP-Servern und vereinfacht den Installationsprozess.

Verwenden von NPM/PNPM

Für die manuelle Installation:

Nach der manuellen Installation müssen Sie Ihre LLM-Anwendung für die Verwendung des MCP-Servers konfigurieren (siehe Abschnitt „Konfiguration“ weiter unten).

Ausführen vom lokalen Repository

Wenn Sie diesen MCP-Server direkt aus dem Quellcode klonen und ausführen möchten, führen Sie die folgenden Schritte aus:

1. Klonen Sie das Repository

   git clone https://github.com/benborla/mcp-server-mysql.git cd mcp-server-mysql

2. Installieren von Abhängigkeiten

   npm install # or pnpm install

3. Erstellen des Projekts

   npm run build # or pnpm run build

4. Claude Desktop konfigurieren

   Fügen Sie Ihrer Claude Desktop-Konfigurationsdatei ( claude_desktop_config.json ) Folgendes hinzu:

   { "mcpServers": { "mcp_server_mysql": { "command": "/path/to/node", "args": [ "/full/path/to/mcp-server-mysql/dist/index.js" ], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false", "PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path "NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"` } } } }

   Ersetzen:

   • /path/to/node mit dem vollständigen Pfad zu Ihrer Node.js-Binärdatei (finden Sie sie mit which node )

   • /full/path/to/mcp-server-mysql mit dem vollständigen Pfad zum geklonten Repository

   • Legen Sie die MySQL-Anmeldeinformationen so fest, dass sie zu Ihrer Umgebung passen

5. Testen des Servers

   # Run the server directly to test node dist/index.js

   Wenn die Verbindung zu MySQL erfolgreich hergestellt wird, können Sie es mit Claude Desktop verwenden.

Komponenten

Werkzeuge

• mysql_query

  • Ausführen von SQL-Abfragen für die verbundene Datenbank

  • Eingabe: sql (Zeichenfolge): Die auszuführende SQL-Abfrage

  • Standardmäßig auf NUR-LESE-Operationen beschränkt

  • Optionale Schreibvorgänge (sofern über die Konfiguration aktiviert):

    • INSERT: Neue Daten zu Tabellen hinzufügen (erfordert ALLOW_INSERT_OPERATION=true )

    • UPDATE: Vorhandene Daten ändern (erfordert ALLOW_UPDATE_OPERATION=true )

    • DELETE: Daten entfernen (erfordert ALLOW_DELETE_OPERATION=true )

  • Alle Vorgänge werden innerhalb einer Transaktion mit ordnungsgemäßer Commit-/Rollback-Behandlung ausgeführt

  • Unterstützt vorbereitete Anweisungen für die sichere Parameterverarbeitung

  • Konfigurierbare Abfrage-Timeouts und Ergebnis-Paginierung

  • Integrierte Abfrageausführungsstatistiken

Ressourcen

Der Server stellt umfassende Datenbankinformationen bereit:

• Tabellenschemata

  • JSON-Schemainformationen für jede Tabelle

  • Spaltennamen und Datentypen

  • Indexinformationen und Einschränkungen

  • Fremdschlüsselbeziehungen

  • Tabellenstatistiken und Metriken

  • Automatisch aus Datenbankmetadaten ermittelt

Sicherheitsfunktionen

• SQL-Injection-Prävention durch vorbereitete Anweisungen

• Abfrage-Whitelisting-/Blacklisting-Funktionen

• Ratenbegrenzung für die Abfrageausführung

• Abfragekomplexitätsanalyse

• Konfigurierbare Verbindungsverschlüsselung

• Durchsetzung schreibgeschützter Transaktionen

Leistungsoptimierungen

• Optimiertes Verbindungspooling

• Zwischenspeichern von Abfrageergebnissen

• Streaming großer Ergebnismengen

• Analyse des Abfrageausführungsplans

• Konfigurierbare Abfrage-Timeouts

Überwachung und Fehlerbehebung

• Umfassende Abfrageprotokollierung

• Erfassung von Leistungsmetriken

• Fehlerverfolgung und -berichterstattung

• Integritätsprüfungsendpunkte

• Abfrageausführungsstatistiken

Konfiguration

Automatische Konfiguration mit Smithery

Wenn Sie Smithery installiert haben, ist Ihre Konfiguration bereits eingerichtet. Sie können sie wie folgt anzeigen oder ändern:

Bei der Neukonfiguration können Sie alle MySQL-Verbindungsdetails sowie die Einstellungen für den Schreibvorgang aktualisieren:

• Grundlegende Verbindungseinstellungen :

  • MySQL-Host, Port, Benutzer, Passwort, Datenbank

  • SSL/TLS-Konfiguration (wenn Ihre Datenbank sichere Verbindungen erfordert)

• Berechtigungen für Schreibvorgänge :

  • INSERT-Operationen zulassen: Auf „true“ setzen, wenn Sie das Hinzufügen neuer Daten zulassen möchten

  • UPDATE-Operationen zulassen: Auf „true“ setzen, wenn Sie die Aktualisierung vorhandener Daten zulassen möchten

  • DELETE-Operationen zulassen: Auf „true“ setzen, wenn Sie das Löschen von Daten zulassen möchten

Aus Sicherheitsgründen sind alle Schreibvorgänge standardmäßig deaktiviert. Aktivieren Sie diese Einstellungen nur, wenn Claude Ihre Datenbankdaten ändern soll.

Erweiterte Konfigurationsoptionen

Um das Verhalten des MCP-Servers besser steuern zu können, können Sie die folgenden erweiterten Konfigurationsoptionen verwenden:

Umgebungsvariablen

Grundlegende Verbindung

• MYSQL_SOCKET_PATH : Unix-Socket-Pfad für lokale Verbindungen (zB "/tmp/mysql.sock")

• MYSQL_HOST : MySQL-Server-Host (Standard: „127.0.0.1“) – wird ignoriert, wenn MYSQL_SOCKET_PATH gesetzt ist

• MYSQL_PORT : MySQL-Server-Port (Standard: „3306“) – wird ignoriert, wenn MYSQL_SOCKET_PATH gesetzt ist

• MYSQL_USER : MySQL-Benutzername (Standard: „root“)

• MYSQL_PASS : MySQL-Passwort

• MYSQL_DB : Name der Zieldatenbank (für den Multi-DB-Modus leer lassen)

Leistungskonfiguration

• MYSQL_POOL_SIZE : Größe des Verbindungspools (Standard: „10“)

• MYSQL_QUERY_TIMEOUT : Abfrage-Timeout in Millisekunden (Standard: „30000“)

• MYSQL_CACHE_TTL : Cache-Lebensdauer in Millisekunden (Standard: „60000“)

Sicherheitskonfiguration

• MYSQL_RATE_LIMIT : Maximale Abfragen pro Minute (Standard: „100“)

• MYSQL_MAX_QUERY_COMPLEXITY : Maximale Abfragekomplexitätsbewertung (Standard: „1000“)

• MYSQL_SSL : SSL/TLS-Verschlüsselung aktivieren (Standard: „false“)

• ALLOW_INSERT_OPERATION : INSERT-Operationen aktivieren (Standard: „false“)

• ALLOW_UPDATE_OPERATION : UPDATE-Operationen aktivieren (Standard: „false“)

• ALLOW_DELETE_OPERATION : DELETE-Operationen aktivieren (Standard: „false“)

• ALLOW_DDL_OPERATION : DDL-Operationen aktivieren (Standard: „false“)

• SCHEMA_INSERT_PERMISSIONS : Schemaspezifische INSERT-Berechtigungen

• SCHEMA_UPDATE_PERMISSIONS : Schemaspezifische UPDATE-Berechtigungen

• SCHEMA_DELETE_PERMISSIONS : Schemaspezifische DELETE-Berechtigungen

• SCHEMA_DDL_PERMISSIONS : Schemaspezifische DDL-Berechtigungen

• MULTI_DB_WRITE_MODE : Schreibvorgänge im Multi-DB-Modus aktivieren (Standard: „false“)

Überwachungskonfiguration

• MYSQL_ENABLE_LOGGING : Abfrageprotokollierung aktivieren (Standard: „false“)

• MYSQL_LOG_LEVEL : Protokollierungsebene (Standard: „info“)

• MYSQL_METRICS_ENABLED : Leistungsmetriken aktivieren (Standard: „false“)

Multi-DB-Modus

MCP-Server-MySQL unterstützt die Verbindung zu mehreren Datenbanken, wenn keine spezifische Datenbank festgelegt ist. Dadurch kann der LLM jede Datenbank abfragen, auf die der MySQL-Benutzer Zugriff hat. Ausführliche Informationen finden Sie in der Datei README-MULTI-DB.md .

Aktivieren des Multi-DB-Modus

Um den Multi-DB-Modus zu aktivieren, lassen Sie die Umgebungsvariable MYSQL_DB einfach leer. Im Multi-DB-Modus erfordern Abfragen eine Schemaqualifizierung:

Schemaspezifische Berechtigungen

Für eine detaillierte Kontrolle von Datenbankoperationen unterstützt MCP-Server-MySQL jetzt schemaspezifische Berechtigungen. Dadurch können verschiedene Datenbanken unterschiedliche Zugriffsebenen haben (schreibgeschützt, Lese-/Schreibzugriff usw.).

Konfigurationsbeispiel

Vollständige Details und Sicherheitsempfehlungen finden Sie unter README-MULTI-DB.md .

Testen

Datenbank-Setup

Bevor Sie Tests ausführen, müssen Sie die Testdatenbank einrichten und mit Testdaten füllen:

1. Testdatenbank und Benutzer erstellen

   -- Connect as root and create test database CREATE DATABASE IF NOT EXISTS mcp_test; -- Create test user with appropriate permissions CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password'; GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost'; FLUSH PRIVILEGES;

2. Datenbank-Setup-Skript ausführen

   # Run the database setup script pnpm run setup:test:db

   Dadurch werden die erforderlichen Tabellen und Seed-Daten erstellt. Das Skript befindet sich in scripts/setup-test-db.ts

3. Testumgebung konfigurieren Erstellen Sie eine .env.test Datei im Projektstamm (falls nicht vorhanden):

   MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=mcp_test MYSQL_PASS=mcp_test_password MYSQL_DB=mcp_test

4. Aktualisieren Sie package.json-Skripte. Fügen Sie diese Skripte zu Ihrem package.json hinzu:

   { "scripts": { "setup:test:db": "ts-node scripts/setup-test-db.ts", "pretest": "pnpm run setup:test:db", "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage" } }

Ausführen von Tests

Das Projekt umfasst eine umfassende Testsuite, um Funktionalität und Zuverlässigkeit sicherzustellen:

Ausführen von Evaluierungen

Das Evals-Paket lädt einen MCP-Client, der anschließend die Datei index.ts ausführt, sodass zwischen den Tests kein Neuaufbau erforderlich ist. Sie können Umgebungsvariablen laden, indem Sie dem Befehl npx voranstellen. Die vollständige Dokumentation finden Sie hier .

Fehlerbehebung

Häufige Probleme

1. Verbindungsprobleme

   • Überprüfen Sie, ob der MySQL-Server ausgeführt wird und zugänglich ist

   • Überprüfen Sie Anmeldeinformationen und Berechtigungen

   • Stellen Sie sicher, dass die SSL/TLS-Konfiguration korrekt ist, falls aktiviert

   • Versuchen Sie, eine Verbindung mit einem MySQL-Client herzustellen, um den Zugriff zu bestätigen

2. Leistungsprobleme

   • Passen Sie die Größe des Verbindungspools an

   • Konfigurieren von Abfrage-Timeoutwerten

   • Aktivieren Sie bei Bedarf das Abfrage-Caching

   • Überprüfen der Einstellungen für die Abfragekomplexität

   • Überwachen der Serverressourcennutzung

3. Sicherheitsbeschränkungen

   • Überprüfen der Ratenbegrenzungskonfiguration

   • Überprüfen Sie die Abfrage-Whitelist-/Blacklist-Einstellungen

   • Überprüfen der SSL/TLS-Einstellungen

   • Stellen Sie sicher, dass der Benutzer über die entsprechenden MySQL-Berechtigungen verfügt

4. Pfadauflösung Wenn der Fehler „Verbindung zum MCP-Server mcp-server-mysql konnte nicht hergestellt werden“ auftritt, legen Sie den Pfad aller erforderlichen Binärdateien explizit fest:

Wo finde ich meinen Führen Sie den folgenden Befehl aus, um ihn abzurufen:

Für PATH

Für NODE_PATH

5. Claude Desktop-spezifische Probleme

   • Wenn Sie in Claude Desktop Protokolle mit der Meldung „Server getrennt“ sehen, überprüfen Sie die Protokolle unter ~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log

   • Stellen Sie sicher, dass Sie den absoluten Pfad sowohl zur Node-Binärdatei als auch zum Serverskript verwenden.

   • Überprüfen Sie, ob Ihre .env Datei ordnungsgemäß geladen wird. Verwenden Sie explizite Umgebungsvariablen in der Konfiguration.

   • Versuchen Sie, den Server direkt über die Befehlszeile auszuführen, um festzustellen, ob Verbindungsprobleme vorliegen

   • Wenn Sie Schreibvorgänge (INSERT, UPDATE, DELETE) benötigen, setzen Sie die entsprechenden Flags in Ihrer Konfiguration auf „true“:

     "env": { "ALLOW_INSERT_OPERATION": "true", // Enable INSERT operations "ALLOW_UPDATE_OPERATION": "true", // Enable UPDATE operations "ALLOW_DELETE_OPERATION": "true" // Enable DELETE operations }

   • Stellen Sie sicher, dass Ihr MySQL-Benutzer über die entsprechenden Berechtigungen für die Vorgänge verfügt, die Sie aktivieren.

   • Verwenden Sie für die Konfiguration der direkten Ausführung:

     { "mcpServers": { "mcp_server_mysql": { "command": "/full/path/to/node", "args": [ "/full/path/to/mcp-server-mysql/dist/index.js" ], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database" } } } }

6. Authentifizierungsprobleme

   • Stellen Sie bei MySQL 8.0+ sicher, dass der Server das Authentifizierungs-Plugin caching_sha2_password unterstützt.

   • Überprüfen Sie, ob Ihr MySQL-Benutzer mit der richtigen Authentifizierungsmethode konfiguriert ist

   • Versuchen Sie bei Bedarf, einen Benutzer mit Legacy-Authentifizierung zu erstellen:

     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

     @lizhuangs

7. Ich stoße auf Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from . Versuchen Sie diese Problemumgehung:

Danke an @lizhuangs

Beitragen

Beiträge sind willkommen! Senden Sie gerne einen Pull Request an https://github.com/benborla/mcp-server-mysql

Vielen Dank an die folgenden Mitwirkenden:

Entwicklungs-Setup

1. Klonen Sie das Repository

2. Abhängigkeiten installieren: pnpm install

3. Erstellen Sie das Projekt: pnpm run build

4. Tests ausführen: pnpm test

Projekt-Roadmap

Wir arbeiten aktiv an der Verbesserung dieses MCP-Servers. Weitere Informationen zu geplanten Funktionen finden Sie in unserer Datei CHANGELOG.md .

• Erweiterte Abfragefunktionen mit vorbereiteten Anweisungen

• Erweiterte Sicherheitsfunktionen

• Leistungsoptimierungen

• Umfassende Überwachung

• Erweiterte Schemainformationen

Wenn Sie zu einem dieser Bereiche beitragen möchten, sehen Sie sich die Probleme auf GitHub an oder eröffnen Sie ein neues, um Ihre Ideen zu diskutieren.

Änderungen übermitteln

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Zweig: git checkout -b feature/your-feature-name

3. Übernehmen Sie Ihre Änderungen: git commit -am 'Add some feature'

4. Pushen zum Zweig: git push origin feature/your-feature-name

5. Senden einer Pull-Anfrage

Lizenz

Dieser MCP-Server ist unter der MIT-Lizenz lizenziert. Weitere Informationen finden Sie in der Datei LICENSE.