postgres-mcp

Ein generischer, wiederverwendbarer MCP-Server für das schreibgeschützte Abfragen beliebiger Postgres-Datenbanken über Claude (oder einen beliebigen MCP-kompatiblen Client). Er kennt kein bestimmtes Schema – list_tables, describe_table und run_sql arbeiten rein über information_schema und generische jsonb-Introspection, sodass er ohne Codeänderungen auf jede Postgres-Datenbank ausgerichtet werden kann.

Sicherheitsmodell

Zwei unabhängige Ebenen, Defense in Depth:

1. Auf DB-Ebene: Der Server verbindet sich als Rolle, der nur SELECT gewährt ist – sie kann selbst dann nichts schreiben, wenn eine Abfrage es versuchte. Diese Rolle erstellst du mit setup_reader_role.sql.

2. Auf Anwendungsebene: run_sql() lehnt alles ab, was kein reines SELECT (bzw. WITH ... SELECT) ist, erzwingt eine Obergrenze von 200 Zeilen und setzt einen Statement-Timeout von 5 Sekunden – alles als Fast-Fail-Check, bevor überhaupt eine Datenbank berührt wird.

Related MCP server: pg-mcp

Setup

1. Erstelle eine Nur-Lese-Rolle in deiner Zieldatenbank:

   • Öffne setup_reader_role.sql, ersetze den Passwort-Platzhalter und <your_db_name> durch echte Werte und führe sie einmal gegen deine Datenbank aus (z. B. über psql oder die SQL-Konsole deines DB-Anbieters).

2. Lege deine Verbindungszeichenfolge in einer .env-Datei in diesem Verzeichnis ab:

   DATABASE_URL=postgresql://mcp_reader:yourpassword@host:5432/yourdb
   ANTHROPIC_API_KEY=sk-ant-...

   (ANTHROPIC_API_KEY wird nur für chat.py benötigt, nicht zum Betrieb des MCP-Servers selbst.)

3. Installiere die Abhängigkeiten:

   pip install -r requirements.txt

Lokal testen

Teste zuerst die Abfrageschicht direkt, ohne dass ein MCP-Client im Spiel ist:

python chat.py "what tables do I have?"

Teste sie dann als echten MCP-Server mit dem Inspector:

fastmcp dev inspector mcp_server.py

Falls die Node-Werkzeugkette des Inspectors Probleme macht (das ist schon vorgekommen), weiche darauf aus, den Server direkt über HTTP laufen zu lassen und ihn mit dem FastMCP-Python-Client anzusprechen:

fastmcp run mcp_server.py --transport http --port 8000

from fastmcp import Client
import asyncio

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        print(await client.call_tool("list_tables", {}))

asyncio.run(main())

Deployment (Prefect Horizon)

Die gehostete Deployment-Plattform von FastMCP heißt derzeit Prefect Horizon (sie hieß vorher „FastMCP Cloud“ – es hat schon einmal ein Rebranding gegeben; überprüfe also den aktuellen Namen bzw. die aktuelle URL unter gofastmcp.com/deployment, bevor du diese Schritte ausführst, falls es erneut geändert wurde).

1. Pushe dieses Repo nach GitHub – ein echtes Remote muss zuerst existieren (siehe die Git-Befehle am Ende dieser README, falls du das noch nicht gemacht hast).

2. Rufe die Website der aktuellen Plattform auf (Stand dieser Anleitung: horizon.prefect.io) und melde dich mit GitHub an.

3. Verbinde dieses Repository.

4. Konfiguriere das Deployment:

   • Einstiegspunkt: mcp_server.py:mcp – der Teil :mcp ist der Variablenname, dem das Server-Objekt in der Datei zugewiesen wird (siehe die Zeile mcp = FastMCP(...) in mcp_server.py). Falls du die Variable jemals umbenennst oder die Datei verschiebst, muss dieser Einstiegspunkt-String exakt entsprechend aktualisiert werden.

   • Authentifizierung: Aktiviere das AN. Interaktive MCP-Clients wie claude.ai und Claude Desktop benötigen echte OAuth-Discovery-Endpunkte – ein Server ohne aktivierte Authentifizierung funktioniert mit dir diesen Clients nicht, auch wenn er bei einem direkten Test mit einem reinen API-Aufruf oder dem FastMCP-Python-Client einwandfrei läuft.

   • Umgebungsvariablen: Füge die DATABASE_URL im eigenen Dashboard der Plattform hinzu. Das ist getrennt von der lokalen .env-Datei dieses Projekts und wird nicht aus ihr gelesen – der Wert muss direkt im Dashboard eingetragen werden, damit der bereitgestellte Server Zugriff auf deine Datenbank bekommt.

5. Führe das Deployment aus und kopiere die resultierenden Server-URL. Sie wird ungefähr so aussehen wie https://<your-server-name>.fastmcp.app/mcp (die genaue Domain kann variieren – verwende das, was dir Plattform tatsächlich anzeigt).

6. Bevor du den Server irgendwo anders anbindest, teste ihn mit dem eingebauten Inspector-/Testtool der Plattform. Rufe dort zuerst list_tables auf – es braucht keine Argumente, ist also der schnellste Weg, um zu bestätigen, dass der bereitgestellte Server deine Datenbank wirklich erreichen kann.

Verbindung zu claude.ai

1. Gehe zu claude.ai → Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen.

2. Füge die Server-URL aus dem bereitgestellten Deployment-Schritt oben ein.

3. Schließe den OAuth-Aufforderungsbildschirm ab, durch den du geführtet wirst.

4. Starte einen neuen Chat (nicht einen, der vor dem Hinzufügen des Connectors bestand) und aktiviere den Connector in diesem Chat.

5. Teste es mit einer einfachen Frage wie „Welche Tabellen habe ich?“

6. Falls du später neue Werkzeuge hinzufügen und sie nicht angezeigt werden, versuche zuerst „Werkzeuge aktualisieren“ in den Connector-Einstellungen, bevor du annimmst, dass etwas defekt ist – das ist ein bekanntes Caching-Verhalten, kein Bug.

Grenzen

Das ist wirklich schema-agnostisch, aber nicht ohne Einschränkungen:

• Postgres-spezifisch. Es nutzt jsonb_object_keys() und die Postgres-Katalogsyntax (information_schema etc.). Eine Ausrichtung auf MySQL oder SQLite würde echte Codeänderungen an db_tools.py notwendig machen, nicht nur neue Verbindungsdaten.

• Schema-agnostisch ≠ kein Einrichtungsaufwand pro Datenbank. Jede neue Zieldatenbank braucht weiterhin eine eigene Nur-Lese-Rolle (via setup_reader_role.sql) und eine eigene Deployment-Instanz (oder zumindest eine eigene DATABASE_URL), die auf sie zeigt. Das ist kein einzelner Server, der transparent mehrere Datenbanken bedient.

Git-Einrichtung

Wenn du diese Basis-Reproduktion noch ohne Git-Historie beginnst:

git init
git add .
git commit -m "Initial commit: generic read-only Postgres MCP server"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main