OmniSQL MCP

Universeller Datenbank-MCP-Server – geben Sie KI-Assistenten Lese-/Schreibzugriff auf Ihre Datenbanken, indem Sie Verbindungen verwenden, die bereits in Ihrem lokalen DB-Client-Arbeitsbereich gespeichert sind (DBeaver-kompatibel).

Dies ist ein Fork von srthkdev/omnisql-mcp, der SSH-Tunnel-/Jump-Host-Unterstützung hinzufügt. Er ist nicht auf npm veröffentlicht – bauen Sie ihn aus diesem Repository (siehe Installation).

Datenbankunterstützung

Nativ unterstützt (direkter Treiber, schnell):

• PostgreSQL (via pg)

• MySQL / MariaDB (via mysql2)

• SQL Server / MSSQL (via mssql)

• SQLite (via sqlite3 CLI)

• Trino / Presto (via trino-client)

Postgres-kompatibel (automatisch über den pg-Treiber geleitet):

• CockroachDB, TimescaleDB, Amazon Redshift, YugabyteDB, AlloyDB, Supabase, Neon, Citus

Andere Datenbanken: Fallback auf eine externe CLI, die über OMNISQL_CLI_PATH konfiguriert ist. Die Ergebnisse variieren je nach CLI.

Related MCP server: DBHub

Funktionen

• Verwendet bereits in Ihrem lokalen DB-Client-Arbeitsbereich konfigurierte Verbindungen erneut – keine doppelte Einrichtung

• Automatische SSH-Tunnel-/Jump-Host-Unterstützung: Stellt transparent über denselben SSH-Tunnel und dasselbe Gateway-/Jump-Host-Profil eine Verbindung her, das für die Verbindung konfiguriert ist (einschließlich verketteter Jump-Server); keine separate Tunneleinrichtung erforderlich

• Native Abfrageausführung für PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Trino/Presto

• Verbindungspooling mit konfigurierbarer Poolgröße und Timeouts (Pooling gilt nicht für SQLite oder Trino/Presto, die pro Abfrage verbindungslos arbeiten)

• Transaktionsunterstützung (BEGIN/COMMIT/ROLLBACK)

• Analyse von Abfrageausführungsplänen (EXPLAIN)

• Schemavergleich zwischen Verbindungen mit Generierung von Migrationsskripten

• Nur-Lese-Modus mit erzwungenem SELECT-only bei execute_query

• Verbindungs-Whitelist, um einzuschränken, welche Datenbanken zugänglich sind

• Tool-Filterung, um bestimmte Operationen zu deaktivieren

• Abfragevalidierung, um gefährliche Operationen zu blockieren (DROP DATABASE, TRUNCATE, DELETE/UPDATE ohne WHERE)

• Datenexport als CSV/JSON

• Graceful Shutdown mit Bereinigung der Verbindungspools

Voraussetzungen

• Node.js 18+

• Ein lokaler DB-Client (DBeaver-kompatibel) mit mindestens einer konfigurierten Verbindung

Installation

Dieser Fork ist nicht auf npm veröffentlicht – bauen Sie ihn aus dem Quellcode:

git clone https://github.com/sangameshBB/omnisql-mcp.git
cd omnisql-mcp
npm install
npm run build

Verknüpfen Sie dann den gebauten Server, sodass der Befehl omnisql-mcp darauf zeigt:

npm install -g .

Führen Sie npm install -g omnisql-mcp nicht für sich allein aus. Dadurch wird das ursprüngliche Upstream-Paket aus der npm-Registry installiert, das keine SSH-Tunnel-/Jump-Host-Unterstützung besitzt. Sie müssen dieses Repository klonen und lokal bauen und dann wie oben gezeigt npm install -g . im geklonten Ordner ausführen.

Konfiguration

Claude Desktop

Fügen Sie Folgendes zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu (macOS):

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Claude Code

Fügen Sie Folgendes zu ~/.claude/settings.json hinzu:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Cursor

Fügen Sie es unter Cursor-Einstellungen > MCP-Server hinzu:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Ohne globale Installation

Wenn Sie npm install -g . nicht ausführen möchten, können Sie Ihren MCP-Client stattdessen direkt auf den gebauten Einstiegspunkt verweisen lassen:

{
  "mcpServers": {
    "omnisql": {
      "command": "node",
      "args": ["/absolute/path/to/omnisql-mcp/dist/index.js"]
    }
  }
}

Umgebungsvariablen

Nur-Lese-Modus

Blockiert alle Schreiboperationen. Das Tool execute_query erlaubt nur SELECT-, EXPLAIN-, SHOW- und DESCRIBE-Anweisungen. Transaktions-Tools sind vollständig deaktiviert.

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_READ_ONLY": "true"
      }
    }
  }
}

Verbindungs-Whitelist

Schränken Sie ein, welche Arbeitsbereichsverbindungen sichtbar sind. Akzeptiert Verbindungs-IDs oder Anzeigenamen, kommagetrennt:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_ALLOWED_CONNECTIONS": "dev-postgres,staging-mysql"
      }
    }
  }
}

Bestimmte Tools deaktivieren

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_DISABLED_TOOLS": "drop_table,alter_table,write_query"
      }
    }
  }
}

Verfügbare Tools

Verbindungsverwaltung

• list_connections - Alle Datenbankverbindungen auflisten

• get_connection_info - Verbindungsdetails abrufen

• test_connection - Konnektivität testen

Datenoperationen

• execute_query - Nur-Lese-Abfragen ausführen (nur SELECT, EXPLAIN, SHOW, DESCRIBE)

• write_query - INSERT/UPDATE/DELETE ausführen

• export_data - Als CSV/JSON exportieren

Schemaverwaltung

• list_tables - Tabellen und Ansichten auflisten

• get_table_schema - Tabellenstruktur abrufen

• create_table - Tabellen erstellen

• alter_table - Tabellen ändern

• drop_table - Tabellen löschen (erfordert Bestätigung)

Transaktionen

• begin_transaction - Eine neue Transaktion starten

• execute_in_transaction - Abfrage innerhalb einer Transaktion ausführen

• commit_transaction - Eine Transaktion committen

• rollback_transaction - Eine Transaktion zurückrollen

Abfrageanalyse

• explain_query - Abfrageausführungsplan analysieren

• compare_schemas - Schemas zwischen zwei Verbindungen vergleichen

• get_pool_stats - Statistiken zum Verbindungspool abrufen

SSH-Tunnel / Jump Host

• get_ssh_tunnel_info - Das einer Verbindung zugeordnete SSH-Tunnel-/Jump-Host-Profil anzeigen (geschwärzt, ohne Geheimnisse)

Sonstiges

• get_database_stats - Datenbankstatistiken

• append_insight - Analysenotizen speichern

• list_insights - Gespeicherte Notizen abrufen

Sicherheit

• Erzwungener Nur-Lese-Modus: execute_query akzeptiert nur Leseanweisungen (SELECT, EXPLAIN, SHOW, DESCRIBE, PRAGMA). Schreiboperationen müssen write_query verwenden.

• Abfragevalidierung: Blockiert DROP DATABASE, DROP SCHEMA, TRUNCATE, DELETE/UPDATE ohne WHERE, GRANT, REVOKE und Anweisungen zur Benutzerverwaltung.

• Verbindungs-Whitelist: Schränken Sie ein, welche Verbindungen über OMNISQL_ALLOWED_CONNECTIONS verfügbar gemacht werden.

• Tool-Filterung: Deaktivieren Sie beliebige Tools über OMNISQL_DISABLED_TOOLS.

• Eingabebereinigung: Verbindungs-IDs und SQL-Bezeichner werden bereinigt, um Injection zu verhindern.

• Empfehlung: Verwenden Sie für den Produktionseinsatz zusätzlich einen Datenbankbenutzer mit Nur-Lese-Berechtigung, um eine mehrschichtige Verteidigung zu erreichen.

Unterstützung für Arbeitsbereichsformate

Unterstützt beide Konfigurationsformate, die von DBeaver-kompatiblen DB-Clients geschrieben werden:

• Legacy: XML-Konfiguration in .metadata/.plugins/org.jkiss.dbeaver.core/

• Modern: JSON-Konfiguration in General/.dbeaver/

Anmeldeinformationen werden automatisch aus der Datei credentials-config.json im Arbeitsbereich entschlüsselt.

SSH-Tunnel-/Jump-Host-Unterstützung

Wenn für eine Verbindung in Ihrem DB-Client ein SSH-Tunnel (Netzwerk-Handler) konfiguriert ist – einschließlich eines oder mehrerer verketteter Jump-Server/Gateway-Hosts – werden jede native Abfrage, jeder test_connection-Aufruf, jede Transaktion und jede gepoolte Verbindung transparent darüber geleitet. Keine separate Tunneleinrichtung ist erforderlich: Der Server öffnet eine lokale Portweiterleitung über dieselbe SSH-Hop-Kette, die Ihr DB-Client verwenden würde, und verbindet den nativen Treiber (pg, mysql2, mssql) mit diesem lokalen Endpunkt.

• Unterstützt Passwort-, Public-Key- und SSH-Agent-Authentifizierung pro Hop

• Unterstützt verkettete Jump-Server (localhost -> jump host(s) -> final SSH host -> database)

• Tunnel werden einmal pro Verbindung geöffnet und über Abfragen hinweg wiederverwendet; beim Herunterfahren geschlossen

• Verwenden Sie get_ssh_tunnel_info, um das Tunnel-/Jump-Host-Profil einer Verbindung anzuzeigen (Host, Port, Authentifizierungstyp, Anzahl der Jump-Server), ohne Geheimnisse preiszugeben

• Wenn ein Passwort oder eine Schlüssel-Passphrase nicht aus dem verschlüsselten Anmeldeinformationsspeicher des Arbeitsbereichs wiederhergestellt werden kann, legen Sie OMNISQL_SSH_PASSWORD, OMNISQL_SSH_PASSPHRASE oder OMNISQL_SSH_PRIVATE_KEY_PATH als Fallback fest

Trino-/Presto-Unterstützung

Trino-Verbindungen funktionieren über HTTPS/HTTP (Basic Auth) mit demselben Host/Benutzer/Passwort, das bereits für die Verbindung gespeichert ist. Einige Trino-spezifische Hinweise:

• Katalog/Schema sind optional. Wenn für die Verbindung kein Standard-Katalog/-Schema konfiguriert ist (häufig beim Durchsuchen mehrerer Kataloge in DBeaver), müssen Abfragen Tabellen vollständig als catalog.schema.table qualifizieren.

• list_tables und get_table_schema sind katalogunabhängig konzipiert (über system.jdbc.tables/system.jdbc.columns), funktionieren also ohne Standard-Katalog – aber in einem großen Multi-Katalog-Cluster werden dadurch Metadaten über jeden Katalog gescannt, was langsam sein kann und doppelte Zeilen zurückgeben kann, wenn derselbe Tabellenname in mehr als einem Katalog/Schema existiert. Verwenden Sie für eine schnelle, eindeutige Suche stattdessen execute_query mit DESCRIBE catalog.schema.table.

• SSH-Tunneling (oben) funktioniert für Trino-Verbindungen genauso wie für jeden anderen Treiber.

• Trino hat in diesem Server kein persistentes Sitzungs-/Transaktionsmodell – begin_transaction und Verbindungspooling sind für Trino-Verbindungen nicht verfügbar (ebenso wie bei SQLite).

Entwicklung

git clone https://github.com/sangameshBB/omnisql-mcp.git
cd omnisql-mcp
npm install
npm run build
npm test
npm run lint

Lizenz

MIT