MySQL MCP Server

Eine Implementierung des Model Context Protocol (MCP), die eine sichere Interaktion mit MySQL-Datenbanken ermöglicht. Diese Serverkomponente stellt die Kommunikation zwischen KI-Anwendungen (Host/Client) und einer MySQL-Datenbank her und macht die Erkundung und Analyse der Datenbank über eine kontrollierte Schnittstelle sicherer und strukturierter.

Hinweis: MySQL MCP Server unterstützt sowohl den Standard-Ein-/Ausgabe-Transport (STDIO) als auch Streamable HTTP (SSE). Für entfernte/self-hosted Bereitstellungen wird der SSE-Modus empfohlen.

Bereitstellung

• Gehostet — Fronteir AI betreibt den Server für Sie, ohne lokale Konfiguration.

• Lokal — Smithery installiert und startet den Server auf Ihrem eigenen Rechner.

Related MCP server: mysql-mcp-server

Funktionen

• Auflisten verfügbarer MySQL-Tabellen als Ressourcen (resources)

• Lesen von Tabelleninhalten

• Ausführen von SQL-Abfragen mit umfassender Fehlerbehandlung

• Mehrdatenbank-Modus (optional MYSQL_DATABASE)

• SSE/HTTP-Transportunterstützung (MCP_TRANSPORT=sse)

• SSH-Tunnel-Unterstützung

• Vollständige Informationen zur Tabellenstruktur

• Stichproben aus Tabellendaten

• Sicherer Datenbankzugriff über Umgebungsvariablen

• Umfassende Protokollierung

Installation

Manuelle Installation

pip install mysql-mcp-server

Installation über Smithery

Verwenden Sie Smithery, um MySQL MCP Server automatisch für Claude Desktop zu installieren:

npx -y @smithery/cli install designcomputer/mysql-mcp-server --client claude

Installation über die Claude Code CLI

claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server

Installation über die Autohand Code CLI

autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server

Mit --scope project nach mcp add bleibt die Registrierung im aktuellen Arbeitsbereich erhalten. Aktuelle CLI-Details finden Sie unter Autohand Code.

Konfiguration

Legen Sie die folgenden Umgebungsvariablen fest:

MYSQL_HOST=localhost     # 数据库主机
MYSQL_PORT=3306         # 可选：数据库端口（不指定时默认 3306）
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # 可选：留空则进入多数据库模式

# 高级配置
MYSQL_SSL_MODE=DISABLED  # DISABLED、REQUIRED、VERIFY_CA、VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # 超时时间（秒）

# 连接行为（可选）
MYSQL_SQL_MODE=TRADITIONAL           # 连接所应用的 SQL mode（默认：TRADITIONAL）

# 兼容性（可选）
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # 例如旧版 MySQL 使用 mysql_native_password
MYSQL_USE_PURE=false     # 强制使用纯 Python 连接器（默认：false）
MYSQL_RAISE_ON_WARNINGS=false        # 出现 SQL 警告时抛出异常（默认：false）

# SSE 传输（可选）
MCP_TRANSPORT=stdio      # stdio 或 sse
MCP_SSE_HOST=0.0.0.0     # 监听所有网卡（Docker/托管部署需要）
PORT=8000                # HTTP 端口（MCP_SSE_PORT 的回退值）
MCP_SSE_ALLOWED_HOSTS=   # 逗号分隔的允许 Host 头（默认：localhost:{port},127.0.0.1:{port}）

# SSH 隧道（可选）
MYSQL_SSH_ENABLE=false   # 设为 true 启用
MYSQL_SSH_HOST=          # SSH 跳板机
MYSQL_SSH_PORT=22        # SSH 端口
MYSQL_SSH_USER=          # SSH 用户名
MYSQL_SSH_KEY_PATH=      # SSH 私钥路径
MYSQL_SSH_REMOTE_HOST=localhost # 从跳板机视角看的目标主机
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

Laden einer .env-Datei

Beim Start lädt der Server die .env-Datei automatisch über python-dotenv. Für die lokale Nutzung genügt:

cp .env.example .env   # 然后填入你的凭据

Die Datei wird aus dem Arbeitsverzeichnis des Prozesses (und dessen übergeordneten Verzeichnissen) gelesen. Wenn Sie den Server selbst im Projektverzeichnis starten, funktioniert dies einwandfrei.

⚠️ Claude Code / Claude Desktop: Diese Hosts starten den Server aus ihrem eigenen Arbeitsverzeichnis und finden die .env im Projekt daher nicht; Sie sehen dann Missing required database configuration. Tragen Sie die MYSQL_*-Werte in den env-Block der MCP-Konfiguration ein (siehe „Verwendung“ unten) und verlassen Sie sich nicht auf .env.

Mehrdatenbank-Modus

Wenn MYSQL_DATABASE nicht gesetzt ist, wechselt der Server in den Mehrdatenbank-Modus:

• list_resources gibt alle Benutzerdatenbanken zurück (Systemdatenbanken werden herausgefiltert)

• Verwenden Sie in SQL-Abfragen vollständig qualifizierte Tabellennamen wie mydb.mytable

• Hinweis: Es wird nur eine einzelne SQL-Anweisung unterstützt; Mehrfachanweisungen (z. B. USE db; SELECT ...) sind nicht möglich.

Verwaltungsseite und Mehrdatenbank-Aliase (SSE-Modus)

Wenn Sie den Server im SSE-Modus starten, können Sie über die integrierte Verwaltungsseite mehrere Datenbankverbindungen verwalten. Für jede Verbindung lassen sich getrennte Lese-/Schreibkonten konfigurieren:

# Windows PowerShell
$env:MCP_TRANSPORT="sse"; $env:MCP_SSE_PORT="8000"; python -m mysql_mcp_server
# Linux/macOS
MCP_TRANSPORT=sse MCP_SSE_PORT=8000 python -m mysql_mcp_server

Verwaltungsseite: http://127.0.0.1:8000/admin/ (nur Loopback-Zugriff – die Verwaltungs-API und die Seite lehnen Nicht-Loopback-Clients und unbekannte Host-Header ab; nicht hinter einen Reverse-Proxy stellen).

Jeder Alias kann konfiguriert werden:

Clients verbinden sich über den Alias: http://127.0.0.1:8000/sse?alias=db1 (wird alias weggelassen, wird der Standard-Alias verwendet). Wenn config/databases.json keine Einträge enthält, dienen die vorhandenen MYSQL_*-Umgebungsvariablen weiterhin als abwärtskompatibler Einzel-Datenbank-Fallback (in diesem Modus verwenden Lese- und Schreibvorgänge dasselbe Konto).

Hinweis zum Unterschied zum Mehrdatenbank-Modus oben: In jenem Modus werden mehrere Schemata über eine einzelne Verbindung exponiert; die Aliase verwalten dagegen mehrere Verbindungen, jeweils mit eigenen Konten und Schreibstrategien.

So werden Schreibvorgänge bestätigt: Der Server stuft jede Anweisung dreistufig ein (Lesen / Schreiben / Löschen). Lesevorgänge werden direkt mit dem Abfragekonto ausgeführt; Schreib- und Löschvorgänge lösen einen MCP-Elicitation-Dialog aus, der das vollständige SQL anzeigt – bei Annahme wird mit dem Schreibkonto ausgeführt, bei Ablehnung abgebrochen. Wenn der Client keine Elicitation unterstützt, entscheidet die write_policy des Alias über das Fallback-Verhalten (siehe Tabelle oben). Alle Schreibversuche werden im Audit-Log der Verwaltungsseite festgehalten (auf der Festplatte unter logs/audit.log).

Verfügbare Tools

execute_sql

Führt beliebige Standard-SQL-Abfragen aus.

• Parameter: query (String)

• Funktionen: Unterstützt SELECT, SHOW, DESCRIBE und DML (INSERT, UPDATE, DELETE). DML-Operationen sind als potenziell zerstörerisch gekennzeichnet.

• Einschränkung: Es wird nur eine einzelne Anweisung unterstützt, keine Mehrfachanweisungen.

• Datenbankübergreifend: Unabhängig von MYSQL_DATABASE kann mit der Schreibweise database.table jede Datenbank abgefragt werden.

get_schema_info

Liefert detaillierte Metadaten zur Datenbankstruktur.

• Parameter: table_name (optionaler String)

• Ausgabe: Spaltennamen, Typen, NULL-Zulässigkeit, Standardwerte und Kommentare.

• Datenbankübergreifend: Mit database.table können Datenbanken außerhalb von MYSQL_DATABASE abgefragt werden; ein Tabellenname ohne Präfix verwendet die konfigurierte Datenbank.

• Bezeichnerregeln: Namen dürfen nur alphanumerische Zeichen, Unterstriche und $ enthalten (ein Punkt als Trennzeichen für database.table ist erlaubt).

get_table_sample

Ruft repräsentative Datenstichproben ab.

• Parameter: table_name (String), limit (optionaler Integer, maximal 20)

• Zweck: Schnelles Verständnis von Datenformat und -inhalt, ohne große Ergebnismengen abrufen zu müssen.

• Datenbankübergreifend: Mit database.table können Stichproben aus Datenbanken außerhalb von MYSQL_DATABASE gezogen werden; ein Tabellenname ohne Präfix verwendet die konfigurierte Datenbank.

• Bezeichnerregeln: Namen dürfen nur alphanumerische Zeichen, Unterstriche und $ enthalten (ein Punkt als Trennzeichen für database.table ist erlaubt).

Verfügbare Prompts

Neben den Tools bietet der Server auch MCP-Prompts an – geführte, mehrstufige Workflows, die der Client bei Bedarf starten kann. In Claude Code erscheinen sie als Slash-Befehle (/mcp__<server>__<prompt>); in Claude Desktop finden Sie sie im Prompt-Menü (+).

Beispiel (Claude Code):

/mcp__mysql__explore_database
/mcp__mysql__analyze_table customers

Beide Prompts orchestrieren die vorhandenen Tools get_schema_info und get_table_sample; explore_database nutzt zusätzlich die Ressourcenliste, um Tabellen aufzulisten.

Verwendung

Mit Claude Desktop

Fügen Sie Folgendes zur claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mysql_mcp_server",
        "run",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Detailliertere Beispiele und agentenspezifische Anleitungen finden Sie in MCP_USECASES.md.

Mit Visual Studio Code

Fügen Sie Folgendes zur mcp.json hinzu:

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mysql-mcp-server",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Hinweis: uv muss zuerst installiert sein.

Debuggen mit MCP Inspector

MySQL MCP Server ist nicht dafür ausgelegt, eigenständig oder direkt über die Python-Befehlszeile gestartet zu werden; Sie können ihn jedoch mit MCP Inspector debuggen.

MCP Inspector bietet eine bequeme Möglichkeit, MCP-Implementierungen zu testen und zu debuggen:

# 安装依赖
pip install -r requirements.txt
# 使用 MCP Inspector 调试（不要直接用 Python 运行）

MySQL MCP Server ist für die Integration in KI-Anwendungen wie Claude Desktop konzipiert und sollte nicht als eigenständiges Python-Programm direkt ausgeführt werden.

Entwicklung

# 克隆仓库
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows 上用 `venv\Scripts\activate`
# 安装开发依赖
pip install -r requirements-dev.txt
# 复制示例配置并填入你的凭据
cp .env.example .env
# 编辑 .env，填入 MySQL 连接信息
# 运行测试
pytest

Sicherheitshinweise

• Bezeichnerprüfung: Die an get_schema_info und get_table_sample übergebenen Tabellen- und Datenbanknamen werden streng per Whitelist geprüft (nur alphanumerische Zeichen, Unterstriche und $; ein Punkt als Trennzeichen für database.table ist erlaubt). Alle anderen Sonderzeichen werden abgelehnt, um SQL-Injection zu verhindern.

• Verschlüsselter Zugriff: Volle Unterstützung für SSL/TLS und SSH-Tunnel, um Remote-Verbindungen abzusichern.

• Datenschutz in Protokollen: Passwörter und SSH-Private Keys werden in Serverprotokollen automatisch maskiert.

• Minimale Rechte: Verwenden Sie stets einen dedizierten MySQL-Benutzer mit minimalen Berechtigungen.

• Der SSE-Transport hat keine eingebaute Authentifizierung. Der SSE-Server bindet standardmäßig an 0.0.0.0 und akzeptiert Verbindungen ohne Anmeldedaten. Wenn er außerhalb von localhost erreichbar sein soll, platzieren Sie ihn hinter einem Reverse-Proxy mit erzwungener Authentifizierung (nginx, Caddy, Traefik). Beispiel für nginx + HTTP Basic Auth:

  location /sse {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
      proxy_buffering off;
  }
  location /messages/ {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
  }

  Setzen Sie MCP_SSE_HOST=127.0.0.1, damit der Server nur auf der Loopback-Adresse lauscht und der Proxy der einzige öffentliche Zugang bleibt. Setzen Sie MCP_SSE_ALLOWED_HOSTS auf den vom Proxy weitergeleiteten öffentlichen Hostnamen (z. B. MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443).

Eine vollständige Anleitung für den sicheren Einsatz finden Sie in SECURITY.md.

Bewährte Sicherheitspraktiken

Diese MCP-Implementierung benötigt Datenbankzugriff, um zu funktionieren. Zur Sicherheit:

1. Erstellen Sie einen dedizierten MySQL-Benutzer und gewähren Sie minimale Berechtigungen

2. Verwenden Sie niemals Root-Anmeldedaten oder Administratorkonten

3. Beschränken Sie den Datenbankzugriff auf die erforderlichen Vorgänge

4. Aktivieren Sie die Protokollierung für die Prüfung

5. Überprüfen Sie den Datenbankzugriff regelmäßig auf Sicherheit

Detaillierte Anweisungen finden Sie im MySQL-Sicherheitskonfigurationsleitfaden, darunter:

• Erstellen eines eingeschränkten MySQL-Benutzers

• Festlegen geeigneter Berechtigungen

• Überwachen des Datenbankzugriffs

• Bewährte Sicherheitspraktiken

⚠️ Wichtig: Befolgen Sie beim Konfigurieren des Datenbankzugriffs unbedingt das Prinzip der geringsten Rechte.

Lizenz

MIT-Lizenz – Einzelheiten finden Sie in der Datei LICENSE.

Mitwirken

1. Forken Sie dieses Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature)

3. Committen Sie Ihre Änderungen (git commit -m 'Add some amazing feature')

4. Pushen Sie den Branch (git push origin feature/amazing-feature)

5. Erstellen Sie einen Pull Request