db-readonly-mcp

Ein MCP-Server, der einem KI-Assistenten (Claude Code, Claude Desktop oder einem anderen MCP-Client) geschützten, schreibgeschützten Zugriff auf eine Postgres-Datenbank gewährt. Fragen Sie z. B. „hol mir alle Händler, die gestern erstellt wurden“ und der Assistent schreibt das SQL und führt es über diesen Server aus, der erzwingt, dass die Abfrage nur Daten lesen kann.

Nur Postgres – andere Datenbanken werden nicht unterstützt.

Warum es das gibt

Einem Assistenten direkten Zugriff auf Ihre Datenbank zu gewähren, ist für Debugging, Datenexploration und die Beantwortung von „wie viele X“-Fragen nützlich, ohne jedes Mal ein Skript zu schreiben. Das Risiko ist offensichtlich: Ein LLM kann halluzinieren oder dazu verleitet werden, eine destruktive Abfrage zu schreiben. Dieser Server existiert, um dieses Risiko nahezu auf null zu reduzieren, mit mehreren unabhängigen Schutzschichten statt sich auf eine einzige zu verlassen.

Related MCP server: Postgres Scout MCP

Sicherheitsmodell

Geschichtet, in der Reihenfolge, in der ihnen tatsächlich vertraut wird:

1. DB-Rolle – die Verbindung verwendet eine dedizierte Postgres-Rolle mit SELECT-nur Berechtigungen. Das ist die eigentliche Grenze: Selbst wenn jede andere Schicht umgangen würde, kann die Rolle nicht schreiben.

2. Abfragevalidierung – lehnt alles ab, was keine einzelne SELECT/WITH ... SELECT-Anweisung ist (keine durch Semikolon getrennten Anweisungen, keine DDL/DML-Schlüsselwörter).

3. Erzwungenes LIMIT – jede Abfrage wird in SELECT * FROM (...) LIMIT N eingebettet, begrenzt auf MAX_LIMIT, unabhängig davon, was angefordert wird.

4. statement_timeout – Abfragen werden nach STATEMENT_TIMEOUT_MS beendet.

5. Startprotokoll – protokolliert die verbundene Datenbank/den Benutzer beim Start auf stderr, damit offensichtlich ist, auf welche DB Sie zeigen, bevor eine Abfrage ausgeführt wird.

Richten Sie diesen Server nur auf eine Dev-/Test-/Staging-Datenbank – niemals auf Produktion. Schichten 2–5 sind Verteidigung in der Tiefe; Schicht 1 (die DB-Rolle) ist die einzige Schicht, der Sie tatsächlich vertrauen sollten, und selbst der sollte nicht mit Produktionsdaten vertraut werden.

Anforderungen

• Node.js >= 20

• Eine Postgres-Datenbank, auf der Sie eine Rolle erstellen können

• Ein MCP-Client (z. B. Claude Code, Claude Desktop oder ein anderer Client, der MCP-Server über stdio unterstützt)

Einrichtung

1. Klonen und installieren

git clone https://github.com/david-mogbeyi/db-readonly-mcp.git
cd db-readonly-mcp
npm install

2. Die schreibgeschützte Rolle erstellen

Führen Sie dies gegen Ihre Ziel-Postgres-Datenbank aus – ersetzen Sie den Rollennamen, das Passwort, den Datenbanknamen und das Schema/den Besitzer, wenn Ihre Anwendung etwas anderes als public verwendet:

CREATE ROLE myapp_readonly WITH LOGIN PASSWORD '<choose-a-password>';
GRANT CONNECT ON DATABASE myapp TO myapp_readonly;
GRANT USAGE ON SCHEMA public TO myapp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO myapp_readonly;

-- Keeps future tables (new migrations) readable automatically, without
-- re-running this grant every time the schema changes.
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO myapp_readonly;

Wenn Ihr Schema nicht public ist oder Sie mehrere Schemas haben, wiederholen Sie die GRANT USAGE/GRANT SELECT/ALTER DEFAULT PRIVILEGES-Zeilen für jedes. Dieser Server fragt derzeit nur das public-Schema für list_tables/describe_table ab, aber query_readonly kann jedes Schema referenzieren, für das der Rolle Zugriff gewährt wurde.

3. Konfigurieren

cp .env.example .env

Bearbeiten Sie .env und setzen Sie DATABASE_URL auf die Verbindungszeichenfolge der schreibgeschützten Rolle:

DATABASE_URL=postgresql://myapp_readonly:<password>@localhost:5432/myapp

Weitere Variablen finden Sie unter Konfiguration unten.

4. Build

npm run build

Dies kompiliert src/ nach dist/ über tsc. Führen Sie es erneut aus, nachdem Sie Änderungen gezogen oder Quellcode bearbeitet haben.

Bei einem MCP-Client registrieren

Claude Code

Fügen Sie im Projekt, aus dem Sie abfragen möchten, eine .mcp.json hinzu (oder bearbeiten Sie Ihre vorhandene):

{
  "mcpServers": {
    "db-readonly": {
      "command": "node",
      "args": ["/absolute/path/to/db-readonly-mcp/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://myapp_readonly:<password>@localhost:5432/myapp"
      }
    }
  }
}

Ersetzen Sie /absolute/path/to/db-readonly-mcp durch den Ort, an dem Sie dieses Repository geklont haben. Starten Sie Claude Code neu (oder verbinden Sie MCP-Server erneut), um es zu übernehmen.

Sie können es auch global statt pro Projekt registrieren – siehe Claude Code MCP Dokumentation für claude mcp add und Scope-Optionen.

Claude Desktop / andere MCP-Clients

Jeder Client, der MCP-Server über stdio unterstützt, kann dies auf die gleiche Weise verwenden: Zeigen Sie auf node /absolute/path/to/db-readonly-mcp/dist/index.js mit DATABASE_URL (und optional den anderen Umgebungsvariablen unten) in seiner Umgebung. Siehe die Dokumentation Ihres Clients für den Ort, an dem seine MCP-Serverkonfiguration liegt – für Claude Desktop ist dies claude_desktop_config.json, mit derselben command/args/env-Form wie oben.

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen (in .env für lokale Ausführungen oder im env-Block Ihrer MCP-Clientkonfiguration).

Tools

Der Server stellt dem Assistenten drei Tools zur Verfügung:

list_tables

Listet Tabellen im public-Schema auf. Keine Argumente.

→ [
    { "table_name": "merchants" },
    { "table_name": "orders" },
    ...
  ]

describe_table(table)

Spalten, Typen, Nullbarkeit und Standardwerte für eine Tabelle im public-Schema.

{ "table": "merchants" }
→ [
    { "column_name": "id", "data_type": "uuid", "is_nullable": "NO", "column_default": "gen_random_uuid()" },
    { "column_name": "created_at", "data_type": "timestamp with time zone", "is_nullable": "NO", "column_default": "now()" },
    ...
  ]

query_readonly(sql, limit?)

Führt eine einzelne geschützte SELECT- (oder WITH ... SELECT)-Anweisung aus. limit ist optional und wird auf MAX_LIMIT begrenzt, selbst wenn ein größerer Wert übergeben wird.

{ "sql": "SELECT id, name, created_at FROM merchants WHERE created_at > now() - interval '1 day'" }
→ { "rowCount": 3, "rows": [ { "id": "...", "name": "...", "created_at": "..." }, ... ] }

Alles, was keine einzelne SELECT/WITH-Anweisung ist – mehrere Anweisungen, DDL, DML, SET usw. – wird abgelehnt, bevor es die Datenbank erreicht, mit einer Erklärung, warum.

Lokale Entwicklung

npm run dev   # runs src/index.ts directly via tsx, loads .env via Node's --env-file

Projektstruktur

src/
  index.ts    # MCP server setup and tool definitions
  sqlGuard.ts # query validation (layer 2 of the safety model)
  db.ts       # Postgres pool setup (statement_timeout, pool size)
  config.ts   # env var loading/validation

Fehlerbehebung

• „DATABASE_URL environment variable is required“ – .env fehlt oder wird nicht geladen; stellen Sie sicher, dass es existiert (aus cp .env.example .env) und dass Ihr MCP-Client env-Block oder npm run dev/npm start es aufnimmt.

• Server protokolliert beim Start die falsche Datenbank/den falschen Benutzer – überprüfen Sie DATABASE_URL; das Startprotokoll (connected as "..." to database "...") wird genau dafür ausgegeben, damit dies leicht zu erkennen ist, bevor eine Abfrage ausgeführt wird.

• „Query rejected: ...“ – die Abfrage war entweder keine einzelne SELECT/WITH Anweisung oder enthielt ein unzulässiges Schlüsselwort. Dies ist Schicht 2 des Sicherheitsmodells wie beabsichtigt, kein Fehler.

• Abfrage hängt und gibt dann einen Fehler aus – wahrscheinlich wird STATEMENT_TIMEOUT_MS erreicht; erhöhen Sie es in .env, wenn Ihre Arbeitslast legitimerweise länger braucht, oder optimieren Sie die Abfrage.

Mitwirken

Issues und PRs sind willkommen. Dies ist absichtlich ein kleines, prüfbares Werkzeug – das Ziel ist es, das Sicherheitsmodell einfach genug zu halten, um es vollständig zu lesen, nicht es zu einem allgemeinen Abfrage-Builder auszubauen.

Lizenz

MIT