PostgreSQL MCP-Server

Ein Model Context Protocol (MCP)-Server, der PostgreSQL-Datenbankverwaltungsfunktionen bereitstellt. Dieser Server unterstützt bei der Analyse vorhandener PostgreSQL-Setups, bietet Implementierungshilfen, behebt Datenbankprobleme, verwaltet Schemata, migriert Daten und überwacht die Datenbankleistung.

Version 0.2.0

Merkmale

Der Server stellt die folgenden Tools bereit:

1. Datenbankanalyse und -einrichtung

1.1. Datenbank analysieren ( `analyze_database` )

Analysiert die Konfiguration und Leistungsmetriken der PostgreSQL-Datenbank:

Konfigurationsanalyse
Leistungsmetriken
Sicherheitsbewertung
Empfehlungen zur Optimierung

// Example usage
{
  "analysisType": "performance" // Optional: "configuration" | "performance" | "security"
}

1.2. Setup-Anweisungen abrufen ( `get_setup_instructions` )

Bietet schrittweise Anleitungen zur Installation und Konfiguration von PostgreSQL:

Plattformspezifische Installationsschritte
Konfigurationsempfehlungen
Bewährte Sicherheitsmethoden
Aufgaben nach der Installation

// Example usage
{
  "platform": "linux", // Required: "linux" | "macos" | "windows"
  "version": "15", // Optional: PostgreSQL version
  "useCase": "production" // Optional: "development" | "production"
}

1.3. Debug-Datenbank ( `debug_database` )

Debuggen Sie häufige PostgreSQL-Probleme:

Verbindungsprobleme
Leistungsengpässe
Sperrkonflikte
Replikationsstatus

// Example usage
{
  "issue": "performance", // Required: "connection" | "performance" | "locks" | "replication"
  "logLevel": "debug" // Optional: "info" | "debug" | "trace"
}

2. Schemaverwaltung

2.1. Schemainformationen abrufen ( `get_schema_info` )

Erhalten Sie detaillierte Schemainformationen für eine Datenbank oder eine bestimmte Tabelle:

Liste der Tabellen in einer Datenbank
Spaltendefinitionen
Einschränkungen (Primärschlüssel, Fremdschlüssel usw.)
Indizes

// Example usage
{
  "tableName": "users" // Optional: specific table to get info for
}

2.2. Tabelle erstellen ( `create_table` )

Erstellen Sie eine neue Tabelle mit den angegebenen Spalten:

Definieren von Spaltennamen und -typen
Festlegen von NULL-Einschränkungen
Festlegen von Standardwerten

// Example usage
{
  "tableName": "users", // Required
  "columns": [ // Required
    { "name": "id", "type": "SERIAL", "nullable": false },
    { "name": "username", "type": "VARCHAR(100)", "nullable": false },
    { "name": "email", "type": "VARCHAR(255)", "nullable": false },
    { "name": "created_at", "type": "TIMESTAMP", "default": "NOW()" }
  ]
}

2.3. Tabelle ändern ( `alter_table` )

Vorhandene Tabellen ändern:

Neue Spalten hinzufügen
Spaltentypen oder Einschränkungen ändern
Spalten löschen

// Example usage
{
  "tableName": "users", // Required
  "operations": [ // Required
    { "type": "add", "columnName": "last_login", "dataType": "TIMESTAMP" },
    { "type": "alter", "columnName": "email", "nullable": false },
    { "type": "drop", "columnName": "temporary_field" }
  ]
}

2.4. Enumerationen abrufen ( `get_enums` )

Erhalten Sie Informationen zu PostgreSQL ENUM-Typen.

// Example usage
{
  "schema": "public", // Optional
  "enumName": "user_status" // Optional
}

2.5. Enumeration erstellen ( `create_enum` )

Erstellen Sie einen neuen ENUM-Typ in der Datenbank.

// Example usage
{
  "enumName": "order_status", // Required
  "values": ["pending", "processing", "shipped", "delivered"], // Required
  "schema": "public", // Optional
  "ifNotExists": true // Optional
}

3. Datenmigration

3.1. Tabellendaten exportieren ( `export_table_data` )

Tabellendaten in das JSON- oder CSV-Format exportieren:

Filtern Sie Daten mit der WHERE-Klausel
Zeilenanzahl begrenzen
Ausgabeformat auswählen

// Example usage
{
  "tableName": "users", // Required
  "outputPath": "./exports/users.json", // Required
  "where": "created_at > '2023-01-01'", // Optional
  "limit": 1000, // Optional
  "format": "json" // Optional: "json" | "csv"
}

3.2. Tabellendaten importieren ( `import_table_data` )

Importieren Sie Daten aus JSON- oder CSV-Dateien:

Optionales Abschneiden der Tabelle vor dem Import
Unterstützung für verschiedene Formate
Benutzerdefinierte CSV-Trennzeichen

// Example usage
{
  "tableName": "users", // Required
  "inputPath": "./imports/users.json", // Required
  "truncateFirst": false, // Optional
  "format": "json", // Optional: "json" | "csv"
  "delimiter": "," // Optional: for CSV files
}

3.3. Zwischen Datenbanken kopieren ( `copy_between_databases` )

Kopieren Sie Daten zwischen zwei PostgreSQL-Datenbanken:

Filtern Sie Daten mit der WHERE-Klausel
Zieltabelle optional kürzen

// Example usage
{
  "sourceConnectionString": "postgresql://user:password@localhost:5432/source_db", // Required
  "targetConnectionString": "postgresql://user:password@localhost:5432/target_db", // Required
  "tableName": "users", // Required
  "where": "active = true", // Optional
  "truncateTarget": false // Optional
}

4. Überwachung

4.1. Datenbank überwachen ( `monitor_database` )

Echtzeitüberwachung der PostgreSQL-Datenbank:

Datenbankmetriken (Verbindungen, Cache-Trefferquote usw.)
Tabellenmetriken (Größe, Zeilenanzahl, tote Tupel)
Informationen zur aktiven Abfrage
Sperrinformationen
Replikationsstatus
Konfigurierbare Warnungen

// Example usage
{
  "includeTables": true, // Optional
  "includeQueries": true, // Optional
  "includeLocks": true, // Optional
  "includeReplication": false, // Optional
  "alertThresholds": { // Optional
    "connectionPercentage": 80,
    "longRunningQuerySeconds": 30,
    "cacheHitRatio": 0.95,
    "deadTuplesPercentage": 10,
    "vacuumAge": 7
  }
}

5. Funktionen

5.1. Funktionen abrufen ( `get_functions` )

Informieren Sie sich über die PostgreSQL-Funktionen.

// Example usage
{
  "functionName": "calculate_total", // Optional
  "schema": "public" // Optional
}

5.2. Funktion erstellen ( `create_function` )

Erstellen oder ersetzen Sie eine PostgreSQL-Funktion.

// Example usage
{
  "functionName": "get_user_count", // Required
  "parameters": "", // Required (empty if no params)
  "returnType": "integer", // Required
  "functionBody": "SELECT count(*) FROM users;", // Required
  "language": "sql", // Optional
  "volatility": "STABLE", // Optional
  "schema": "public", // Optional
  "security": "INVOKER", // Optional
  "replace": true // Optional
}

5.3. Drop-Funktion ( `drop_function` )

Löschen Sie eine PostgreSQL-Funktion.

// Example usage
{
  "functionName": "old_function", // Required
  "parameters": "integer", // Optional: required for overloaded functions
  "schema": "public", // Optional
  "ifExists": true, // Optional
  "cascade": false // Optional
}

6. Sicherheit auf Zeilenebene (RLS)

6.1. RLS aktivieren ( `enable_rls` )

Aktivieren Sie die Sicherheit auf Zeilenebene für eine Tabelle.

// Example usage
{
  "tableName": "sensitive_data", // Required
  "schema": "secure" // Optional
}

6.2. RLS deaktivieren ( `disable_rls` )

Deaktivieren Sie die Sicherheit auf Zeilenebene für eine Tabelle.

// Example usage
{
  "tableName": "sensitive_data", // Required
  "schema": "secure" // Optional
}

6.3. RLS-Richtlinie erstellen ( `create_rls_policy` )

Erstellen Sie eine Sicherheitsrichtlinie auf Zeilenebene.

// Example usage
{
  "tableName": "documents", // Required
  "policyName": "user_can_see_own_docs", // Required
  "using": "owner_id = current_user_id()", // Required
  "check": "owner_id = current_user_id()", // Optional
  "schema": "public", // Optional
  "command": "SELECT", // Optional
  "role": "app_user", // Optional
  "replace": false // Optional
}

6.4. RLS-Richtlinie bearbeiten ( `edit_rls_policy` )

Bearbeiten Sie eine vorhandene Sicherheitsrichtlinie auf Zeilenebene.

// Example usage
{
  "tableName": "documents", // Required
  "policyName": "user_can_see_own_docs", // Required
  "schema": "public", // Optional
  "roles": ["app_user", "admin_user"], // Optional: New roles (empty or omit to keep existing/use default)
  "using": "owner_id = current_user_id() OR is_admin(current_user_id())", // Optional: New USING expression
  "check": "owner_id = current_user_id()" // Optional: New WITH CHECK expression
}

6.5. RLS-Richtlinie löschen ( `drop_rls_policy` )

Löschen Sie eine Sicherheitsrichtlinie auf Zeilenebene.

// Example usage
{
  "tableName": "documents", // Required
  "policyName": "old_policy", // Required
  "schema": "public", // Optional
  "ifExists": true // Optional
}

6.6. RLS-Richtlinien abrufen ( `get_rls_policies` )

Rufen Sie Sicherheitsrichtlinien auf Zeilenebene ab.

// Example usage
{
  "tableName": "documents", // Optional
  "schema": "public" // Optional
}

7. Auslöser

7.1. Trigger abrufen ( `get_triggers` )

Informieren Sie sich über PostgreSQL-Trigger.

// Example usage
{
  "tableName": "audit_log", // Optional
  "schema": "public" // Optional
}

7.2. Trigger erstellen ( `create_trigger` )

Erstellen Sie einen PostgreSQL-Trigger.

// Example usage
{
  "triggerName": "log_user_update", // Required
  "tableName": "users", // Required
  "functionName": "audit_user_change", // Required
  "schema": "public", // Optional
  "timing": "AFTER", // Optional
  "events": ["UPDATE"], // Optional
  "when": "OLD.email IS DISTINCT FROM NEW.email", // Optional
  "forEach": "ROW", // Optional
  "replace": false // Optional
}

7.3. Auslöser fallen lassen ( `drop_trigger` )

Löschen Sie einen PostgreSQL-Trigger.

// Example usage
{
  "triggerName": "old_trigger", // Required
  "tableName": "users", // Required
  "schema": "public", // Optional
  "ifExists": true, // Optional
  "cascade": false // Optional
}

7.4. Trigger-Status festlegen ( `set_trigger_state` )

Aktivieren oder deaktivieren Sie einen PostgreSQL-Trigger.

// Example usage
{
  "triggerName": "log_user_update", // Required
  "tableName": "users", // Required
  "enable": false, // Required: true to enable, false to disable
  "schema": "public" // Optional
}

Voraussetzungen

Node.js >= 18.0.0
PostgreSQL-Server (für Zieldatenbankvorgänge)
Netzwerkzugriff auf Ziel-PostgreSQL-Instanzen

Installation

Installation über Smithery

So installieren Sie den PostgreSQL-MCP-Server für Claude Desktop automatisch über Smithery :

npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude

Manuelle Installation

Klonen Sie das Repository
Installieren Sie Abhängigkeiten:
npm install
Erstellen Sie den Server:
npm run build
Zur MCP-Einstellungsdatei hinzufügen (z. B. in den Einstellungen Ihrer IDE oder einer globalen MCP-Konfiguration):Es gibt mehrere Möglichkeiten, die Verbindungszeichenfolge für den Server zu konfigurieren. Dabei gilt die folgende Rangfolge:
1. Toolspezifisches Argument : Wenn beim Aufruf eines bestimmten Tools direkt in den Argumenten eine connectionString angegeben wird, wird dieser Wert für diesen Aufruf verwendet.
2. CLI-Argument : Sie können beim Starten des Servers mit dem Argument -cs oder --connection-string eine Standardverbindungszeichenfolge angeben.
3. Umgebungsvariable : Wenn keine der oben genannten Optionen angegeben ist, sucht der Server nach einer Umgebungsvariablen POSTGRES_CONNECTION_STRING .
Wenn mit keiner dieser Methoden eine Verbindungszeichenfolge gefunden wird, schlagen Tools fehl, die eine Datenbankverbindung erfordern.
Beispiel für die Verwendung des CLI-Arguments in den MCP-Einstellungen:
{ "mcpServers": { "postgresql-mcp": { "command": "node", "args": [ "/path/to/postgresql-mcp-server/build/index.js", "--connection-string", "postgresql://username:password@server:port/dbname" // Optionally, add "--tools-config", "/path/to/your/mcp-tools.json" ], "disabled": false, "alwaysAllow": [] // Note: 'env' block for POSTGRES_CONNECTION_STRING can still be used as a fallback // if --connection-string is not provided in args. } } }
Beispiel mit Umgebungsvariable (wenn kein CLI-Argument verwendet wird):
{ "mcpServers": { "postgresql-mcp": { "command": "node", "args": [ "/path/to/postgresql-mcp-server/build/index.js" // Optionally, add "--tools-config", "/path/to/your/mcp-tools.json" ], "disabled": false, "alwaysAllow": [], "env": { "POSTGRES_CONNECTION_STRING": "postgresql://username:password@server:port/dbname" } } } }
Durch die Verwendung des CLI-Arguments --connection-string oder der Umgebungsvariablen POSTGRES_CONNECTION_STRING wird das Argument connectionString für die meisten Toolaufrufe optional.

Werkzeugkonfiguration

Der Server unterstützt das Filtern, welche Tools über eine externe JSON-Konfigurationsdatei aktiviert werden.

CLI-Option : Verwenden Sie -tc <path> oder --tools-config <path> um den Pfad zu Ihrer Tool-Konfigurationsdatei anzugeben.
Dateiformat : Die JSON-Datei sollte ein Objekt mit einem Schlüssel enabledTools enthalten, der ein Array von Tool-Namenszeichenfolgen enthält.Beispiel mcp-tools.json :
{ "enabledTools": [ "get_schema_info", "analyze_database", "export_table_data" ] }
Verhalten :
- Wenn die Konfigurationsdatei bereitgestellt und gültig ist, werden nur die aufgelisteten Tools aktiviert.
- Wenn die Datei nicht bereitgestellt wird, ungültig ist oder nicht gelesen werden kann, werden standardmäßig alle Tools aktiviert.
- Der Server protokolliert, welche Tools basierend auf dieser Konfiguration aktiviert sind.

Entwicklung

npm run dev - Entwicklungsserver mit Hot Reload starten
npm run lint – ESLint ausführen
npm test – Tests ausführen (falls konfiguriert)

Sicherheitsüberlegungen

Verbindungssicherheit
- Der Server ermittelt die Datenbankverbindungszeichenfolge basierend auf der folgenden Priorität:
  1. connectionString die direkt in den Argumenten eines Tools bereitgestellt wird.
  2. --connection-string CLI-Argument, das beim Starten des Servers verwendet wird.
  3. Umgebungsvariable POSTGRES_CONNECTION_STRING .
- Stellen Sie sicher, dass Verbindungszeichenfolgen (insbesondere solche mit Anmeldeinformationen) sicher verwaltet werden.
- Verwendet Verbindungspooling über pg (vorher @vercel/postgres ).
- Überprüft Verbindungszeichenfolgen.
- Unterstützt SSL/TLS-Verbindungen (Konfiguration über Verbindungszeichenfolge).
Abfragesicherheit
- Führt vordefinierte Operationen aus und vermeidet nach Möglichkeit die willkürliche Ausführung von SQL.
- Verwendet gegebenenfalls parametrisierte Abfragen, um SQL-Injection zu verhindern.
- Protokolliert Vorgänge zur Prüfung.
Authentifizierung
- Basiert auf den Authentifizierungsmechanismen von PostgreSQL über die Verbindungszeichenfolge.
- Verwalten Sie Ihre Datenbankanmeldeinformationen sicher. Verwenden Sie diese, wenn möglich, nicht fest in Client-Anfragen. Verwenden Sie bei der Serverkonfiguration vorzugsweise die CLI-Option --connection-string oder die Umgebungsvariable POSTGRES_CONNECTION_STRING .

Bewährte Methoden

Konfigurieren Sie die Standard-Datenbankverbindungszeichenfolge sicher mit der CLI-Option --connection-string oder der Umgebungsvariablen POSTGRES_CONNECTION_STRING .
Wenn ein Tool eine Verbindung zu einer anderen Datenbank als der Standarddatenbank herstellen muss, geben Sie die connectionString direkt in den Argumenten dieses Tools an.
Verwenden Sie immer sichere Verbindungszeichenfolgen mit den richtigen Anmeldeinformationen, vorzugsweise konfiguriert über die Umgebungsvariable POSTGRES_CONNECTION_STRING .
Befolgen Sie die Produktionssicherheitsempfehlungen für sensible Umgebungen.
Überwachen und analysieren Sie die Datenbankleistung regelmäßig mit dem Tool monitor_database .
Halten Sie die PostgreSQL-Version auf dem neuesten Stand.
Implementieren Sie selbstständig geeignete Backup-Strategien.
Verwenden Sie Verbindungspooling für eine bessere Ressourcenverwaltung (intern gehandhabt).
Implementieren Sie eine ordnungsgemäße Fehlerbehandlung und -protokollierung.
Regelmäßige Sicherheitsüberprüfungen und -updates.

Fehlerbehandlung

Der Server implementiert die Fehlerbehandlung für:

Verbindungsfehler
Abfragefehler
Ungültige Eingaben
Berechtigungsprobleme

Fehler werden im standardmäßigen MCP-Fehlerformat zurückgegeben.

Beitragen

Forken Sie das Repository
Erstellen eines Feature-Zweigs
Übernehmen Sie Ihre Änderungen
Push zum Zweig
Erstellen einer Pull-Anforderung

Lizenz

Dieses Projekt ist unter der AGPLv3-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE.

Integrations