mysql-mcp-server

Ein Model Context Protocol (MCP)-Server, der es einem MCP-Client (Claude Desktop, Claude Code usw.) ermöglicht, SQL über vier Tools gegen eine MySQL-Datenbank auszuführen: select, insert, update und delete.

Der Server läuft als uv-verwaltetes Python-Paket und kommuniziert als ein vom Client gestarteter Subprozess über stdio mit dem Client.

Anforderungen

• Python 3.11+

• uv

• Ein erreichbarer MySQL-Server

Related MCP server: Universal Database MCP Server

Installation

uv sync

Konfiguration

Der Server benötigt sechs Werte, die jeweils über Umgebungsvariable und/oder CLI-Flag gesetzt werden können (CLI-Flags haben Vorrang vor Umgebungsvariablen):

Wenn ein erforderlicher Wert fehlt oder MYSQL_MODE nicht readonly/readwrite ist, gibt der Server eine Fehlermeldung auf stderr aus und beendet sich mit Statuscode 1, ohne zu starten.

• readonly-Modus: Nur das select-Tool ist erlaubt. insert/update/delete werden mit einem PERMISSION_DENIED-Fehler abgelehnt.

• readwrite-Modus: Alle vier Tools sind erlaubt.

Der Modus ist für die Lebensdauer des Prozesses festgelegt; er kann zur Laufzeit nicht geändert werden.

Sicherheitsempfehlung: Der readonly-Modus ist eine Schutzmaßnahme auf Anwendungsebene, kein Ersatz für Datenbankberechtigungen. Wo möglich, sollte der readonly-Modus auf ein MySQL-Konto verweisen, das nur SELECT-Berechtigungen hat.

Ist eine .env-Datei erforderlich? Nein. Der Server selbst liest niemals .env-Dateien — er liest nur CLI-Flags und echte Prozess-Umgebungsvariablen (os.environ). Wie Sie Werte in diese Umgebung bekommen, hängt davon ab, wie Sie ihn ausführen:

• Als MCP-Server (siehe Verbindung über einen MCP-Client herstellen unten): Der Client (Claude Desktop/Code) startet den Serverprozess und injiziert den env-Block aus seiner eigenen JSON-Konfiguration direkt als Umgebungsvariablen. Es ist keine .env-Datei beteiligt oder erforderlich.

• CLI direkt für lokale Entwicklung/Tests ausführen: .env ist nur eine Annehmlichkeit, damit Sie nicht sechs Variablen von Hand exportieren müssen. Kopieren Sie .env.example nach .env, füllen Sie echte Werte ein und laden Sie sie explizit — sie wird nicht automatisch gelesen:

  uv run --env-file .env mysql-mcp-server

  .env ist git-ignoriert und darf niemals eingecheckt werden.

Ausführen

# Environment variables (or use `uv run --env-file .env mysql-mcp-server`, see above)
export MYSQL_MODE=readonly
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=app_user
export MYSQL_PASSWORD=secret
export MYSQL_DATABASE=mydb
uv run mysql-mcp-server

# Or, equivalently, via CLI flags
uv run mysql-mcp-server \
  --mysql-mode readonly \
  --mysql-host 127.0.0.1 \
  --mysql-port 3306 \
  --mysql-user app_user \
  --mysql-password secret \
  --mysql-database mydb

Verbindung über einen MCP-Client herstellen

Claude Desktop / Claude Code

Fügen Sie einen Eintrag zur Serverkonfiguration Ihres MCP-Clients hinzu (z. B. claude_desktop_config.json von Claude Desktop oder .mcp.json für Claude Code):

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mysql-mcp-server",
        "run",
        "mysql-mcp-server"
      ],
      "env": {
        "MYSQL_MODE": "readonly",
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "app_user",
        "MYSQL_PASSWORD": "secret",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}

Starten Sie den Client nach dem Bearbeiten der Konfiguration neu. Die Tools select, insert, update und delete (abhängig von MYSQL_MODE) sollten dann für das Modell verfügbar sein.

Tools

Alle vier Tools akzeptieren {"query": string, "params"?: array} und verwenden in query immer %s-Parameterbindungs-Platzhalter — Benutzereingaben dürfen niemals per String-Formatierung in eine Abfrage eingefügt werden.

Jeder Tool-Aufruf gibt eines von Folgendem zurück:

{ "success": true, "data": { ... } }

{ "success": false, "error": { "code": "...", "message": "..." } }

Fehlercodes: PERMISSION_DENIED, INVALID_QUERY_TYPE, MULTI_STATEMENT_NOT_ALLOWED, DB_CONNECTION_ERROR, DB_EXECUTION_ERROR, INTERNAL_ERROR.

Mehrfachabfragen (;-getrennt) und alle DDL-/Berechtigungsanweisungen (DROP, TRUNCATE, ALTER, GRANT, CREATE USER, ...) werden immer abgelehnt, da nur die vier oben genannten Whitelist-Anweisungstypen jemals akzeptiert werden.

Entwicklung

uv sync
uv run ruff format .
uv run ruff check .
uv run pytest -v
uv run uv build   # packaging check

Fehlerbehebung

• Server beendet sich sofort mit Status 1: Ein erforderlicher MYSQL_*-Wert fehlt oder MYSQL_MODE ist ungültig — prüfen Sie stderr, um zu sehen, welcher es ist.

• DB_CONNECTION_ERROR: MySQL ist nicht erreichbar oder die Anmeldedaten sind falsch. Der Server läuft weiter und versucht die Verbindung beim nächsten Tool-Aufruf erneut.

• PERMISSION_DENIED bei insert/update/delete: Der Server läuft im readonly-Modus; starten Sie ihn mit MYSQL_MODE=readwrite neu, wenn Schreibvorgänge beabsichtigt sind.

Versionsverlauf

• 0.1.0 — Erste Veröffentlichung: select/insert/update/delete-Tools, readonly/readwrite-Modusrichtlinie, stdio-MCP-Transport, automatisches Wiederverbinden und erneuter Versuch bei verlorenen Verbindungen.