pg-mcp

PostgreSQL-Abfragedienst in natürlicher Sprache via MCP (Model Context Protocol). Verwendet OpenAI, um natürliche Sprache in SQL zu übersetzen, validiert und führt es sicher aus und gibt Ergebnisse an jeden MCP-kompatiblen Client zurück.

Funktionen

• Natürliche Sprache zu SQL via OpenAI

• Automatische Erkennung des Datenbankschemas beim Start (Tabellen, Views, Spalten, Indizes, Fremdschlüssel, Enums)

• Schemacache mit optionaler Persistenz auf der Festplatte

• SQL-Sicherheitsvalidierung (nur SELECT, Blockierung gefährlicher Funktionen, Durchsetzung von LIMIT)

• Ausführung von schreibgeschützten Transaktionen mit konfigurierbarem Timeout

• Ergebnisvalidierung mit automatischem Wiederholungsversuch bei leeren Ergebnissen

• Unterstützt mehrere Datenbanken

Related MCP server: PostgreSQL MCP Server

Anforderungen

• Python 3.11+

• PostgreSQL

• OpenAI API-Schlüssel

Installation

pip install -e .

Für die Entwicklung:

pip install -e ".[dev]"

Konfiguration

Kopieren Sie .env.example nach .env und tragen Sie Ihre Werte ein:

cp .env.example .env

Beispiel für mehrere Datenbanken:

PG_MCP_DATABASES=postgresql://user:pass@host1:5432/db1,postgresql://user:pass@host2:5432/db2

Verwendung mit Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "pg-mcp": {
      "command": "pg-mcp",
      "args": [],
      "env": {
        "PG_MCP_DATABASES": "postgresql://user:pass@localhost:5432/mydb",
        "OPENAI_API_KEY": "sk-...",
        "PG_MCP_SCHEMA_CACHE_PATH": "~/.cache/pg-mcp/schema.json"
      }
    }
  }
}

MCP-Tools

query

Fragen Sie eine Datenbank in natürlicher Sprache ab.

{
  "question": "What are the top 10 customers by sales last month?",
  "database": "mydb",
  "return_sql": false,
  "max_rows": 100
}

• return_sql: true — gibt das generierte SQL zurück, ohne es auszuführen

• return_sql: false (Standard) — führt es aus und gibt Ergebnisse zurück

list_databases

Listet alle zugänglichen Datenbanken mit zusammenfassenden Informationen auf.

describe_database

Ruft detaillierte Schemainformationen für eine Datenbank ab.

{
  "database": "mydb",
  "schema": "public",
  "pattern": "user"
}

refresh_schema

Lädt den Schemacache aus der Datenbank neu.

{
  "database": "mydb"
}

Lassen Sie database weg, um alle Datenbanken zu aktualisieren.

Testen mit Fixture-Datenbanken

Das Verzeichnis fixtures/ bietet drei vorgefertigte Datenbanken für lokale Tests.

Einrichtung

# From project root, create & seed all fixture databases
cd fixtures
make all

# Or create individual ones
make small     # pg_mcp_test_small  — bookshelf (4 tables, ~50 rows)
make medium    # pg_mcp_test_medium — ecommerce (12 tables, ~500 rows)
make large     # pg_mcp_test_large  — enterprise (28 tables, ~5000 rows)

Überschreiben Sie die PostgreSQL-Anmeldedaten über die Umgebung (Standard: root / admin123 @ localhost:5432):

make all PGUSER=myuser PGPASSWORD=mypass PGHOST=127.0.0.1

.env konfigurieren

Verweisen Sie PG_MCP_DATABASES auf die Fixture-Datenbanken:

PG_MCP_DATABASES=postgresql://root:admin123@localhost:5432/pg_mcp_test_small,postgresql://root:admin123@localhost:5432/pg_mcp_test_medium,postgresql://root:admin123@localhost:5432/pg_mcp_test_large

Testen mit dem MCP Inspector

Verwenden Sie den integrierten MCP-Inspector für interaktive Tests:

cd /path/to/postgres-mcp
fastmcp dev src/pg_mcp/server.py:mcp

Dies öffnet eine Browser-Benutzeroberfläche, in der Sie Tools wie query, list_databases und describe_database direkt aufrufen können.

Testen mit Claude Desktop

Fügen Sie dies zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "pg-mcp": {
      "command": "python3",
      "args": ["-m", "pg_mcp.server"],
      "cwd": "/path/to/postgres-mcp"
    }
  }
}

Hinweis: Bei Verwendung von cwd liest der Server .env aus diesem Verzeichnis. Sie können Umgebungsvariablen auch über den Schlüssel "env" übergeben.

Testabfragen

Sobald die Verbindung hergestellt ist, versuchen Sie diese Abfragen in natürlicher Sprache gegen die Fixture-Datenbanken:

Bereinigung

cd fixtures
make drop-all      # Remove all fixture databases
make refresh-all   # Drop + recreate + re-seed

Tests ausführen

python3 -m pytest tests/ -v

Funktionsweise

User question
  → Schema context assembled from cache
  → OpenAI generates SQL
  → Safety validation (SELECT-only, no dangerous functions, LIMIT injection)
  → Execute in read-only transaction with timeout
  → Optional result validation on empty results
  → Return SQL or query results

Sicherheit

• Generiertes SQL wird darauf validiert, nur SELECT-Anweisungen zu enthalten (einschließlich CTE-Prüfungen)

• Über 40 gefährliche PostgreSQL-Funktionen sind blockiert (Sitzungssteuerung, Advisory Locks, dblink, Dateisystemzugriff, Sequenzmutation, etc.)

• Alle Abfragen werden in schreibgeschützten Transaktionen ausgeführt

• Automatische LIMIT-Durchsetzung verhindert große Ergebnismengen

• Abfrage-Timeout verhindert lang laufende Abfragen

• Verbindungspasswörter erscheinen niemals in Protokollen oder API-Antworten