@cocaxcode/database-mcp

Kurzüberblick

Der vollständigste MCP-Server für Datenbanken. 33 Tools für 3 Engines (PostgreSQL, MySQL, SQLite) mit Verbindungsgruppen, benannten Verbindungen, automatischem Rollback, Dump/Restore, Schema-Auto-Erkennung über MCP-Ressourcen und vollständigem Abfrageverlauf – alles über natürliche Sprache.

Das ist nicht nur ein einfacher Abfrage-Ausführer. Es ist eine vollständige Datenbank-Workbench: organisiere Verbindungen in Gruppen, die auf deine Projektverzeichnisse abgestimmt sind, setze Standardwerte, die zwischen Sitzungen erhalten bleiben, inspiziere Schemas auf drei Detailebenen, erhalte Snapshots vor jeder Mutation, mache Fehler mit Reverse-SQL rückgängig, sichere und stelle ganze Datenbanken per Dump/Restore wieder her und verfolge jede Abfrage, die du ausführst – pro Projekt, pro Verbindung.

Jede Verbindung gehört zu einer Gruppe. Gruppen sind die organisatorische Einheit für deine Datenbankverbindungen – sie sorgen für Abgrenzung, Übersichtlichkeit und Laptop Autiomatik. Wenn du in einem Scope-Verzeichnis arbeitest, siehst du nur die Verbindungen dieser Gruppe – keine Unübersichtlichkeit, keine Verwirrung.

Du beschreibst, was du brauchst. Die KI liest dein Schema, schreibt das SQL und führt es sicher aus – mit automatischer LIMIT-Ergänzung, Snapshots vor Mutationen und Bestätigung vor destruktiven Operationen. Keine Cloud-Konten, keine ORMs, keine Konfigurationsdateien. Zugangsdaten verlassen niemals deinen Rechner. Alles läuft lokal.

Funktioniert mit Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI, Gemini CLI und jedem MCP-kompatiblen Client.

Related MCP server: Database MCP Server

Einfach mit dem Server sprechen

Du brauchst dir keine Tool-Namen oder SQL-Syntax einprägen. Sag einfach, was du möchtest.

> "Connect to my local PostgreSQL on port 5432, database myapp, user admin"

> "Create a group called backend and add this directory"

> "Connect to my PostgreSQL on localhost, put it in the backend group"

> "Set local-pg as the default connection"

> "Show me all tables"

> "What columns does the users table have?"

> "Show me the last 10 orders with the customer name"
  -> AI reads FKs from schema, builds the JOIN, applies LIMIT 10

> "Insert a test user called Alice"
  -> Snapshot captured for rollback

> "Oops, undo that"
  -> Rows restored via reverse SQL

> "Switch to the production database for this session"
  -> Instant context change, all queries now go to prod

> "Delete all inactive users"
  -> "This will affect N rows. Call again with confirm=true to proceed."

> "What did I run today?"
  -> Full query history with timestamps and execution times

> "Dump the database — structure and data"
  -> SQL file generated, ready for restore

Die KI kennt dein Schema bereits über MCP-Ressourcen. Sie liest die db://schema-Ressource, um Tabellen zu entdecken, und db://tables/{name}/schema für Spalten, Fremdschlüssel und Indizes. Wenn du Daten spranz allen Tabellen abfragst, baut sie die korrekten JOINs automatisch auf.

Verbindungsgruppen

Jede Verbindung gehört zu einer Gruppe. Gruppen sind die organisatorische Einheit für deine Datenbankverbindungen – sie halten alles abgegrenzt, sauber und automatisch.

Eine Gruppe basiert auf drei Schlüsselkonzepten:

• Scopes: Verzeichnisse, die sich die Verbindungen der Gruppe teilen. Wenn du in einem überwachten Verzeichnis arbeitest, siehst du nur die Verbindungen dieser Gruppe. Kein globales Durchäumeinanders.

• Standard: die Verbindung, die automatisch aktiviert wird, sobald du ein Scoped-Verzeichnis betrittst. Sie bleibt zwischen Sitzungen erhalten.

• Aktiv: die Verbindung, die gerade verwendet wird. Nur für die aktuelle Sitzung – nach dem Neustart wird wieder die Standardverbindung verwendet.

So sieht ein praktischer Arbeitsablauf aus:

"Create a group called backend"
"Add this directory as scope"
"Create a PostgreSQL connection called local-dev in the backend group"   <- auto-default (first connection)
"Create another called production in backend"
"List connections"                                                       <- shows local-dev (active, default)
"Switch to production"                                                   <- session only
"Set production as default"                                              <- persists between sessions

Die erste Verbindung, die du zu einer Gruppe hinzufügst, wird automatisch zur Standardverbindung. Der Wechsel der Verbindung verändert nur den aktiven Status fürdie aktuelle Sitzung – nach dem Neustart kehrst du zur Standardverbindung zurück. Wenn du möchtest, dass die Änderung dauerhaft bleibt, setze ausdrücklich eine Neue Standardverbindung.

Das bedeutet: Du kannst bedenkenlos für eine kurze Abfrage auf die Produktion wechseln und weißt, dass du beim nächsten Öffnen des Projekts wieder auf deiner Entwicklungsdatenbank landest.

Installation

Claude Code

claude mcp add --scope user database -- npx -y @cocaxcode/database-mcp@latest

Claude Desktop

Füge in deiner Konfigurationsdatei hinzu (~/Library/Application Support/Claude/claude_desktop_config.json unter macOS, %APPDATA%\Claude\claude_desktop_config.json unter Windows):

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

Füge in .cursor/mcp.json oder .windsurf/mcp.json im Projektverzeichnis hinzu:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

Füge in .vscode/mcp.json hinzu:

{
  "servers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

codex mcp add database -- npx -y @cocaxcode/database-mcp@latest

Oder füge in ~/.codex/config.toml hinzu:

[mcp_servers.database]
command = "npx"
args = ["-y", "@cocaxcode/database-mcp@latest"]

Füge in ~/.gemini/settings.json hinzu:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

Treiberinstallation

Installiere nur die Treiber, du brauchst – sie werden zur Laufzeit dynamisch geladen:

npm install -g postgres       # PostgreSQL (postgres.js)
npm install -g mysql2         # MySQL
npm install -g sql.js         # SQLite (runs in-process, no native bindings)

Hinweis: Bei Verwendung von npx müssen die Treiber global installiert werden. Wenn du den Server global installierst (npm install -g @cocaxcode/database-mcp), können die Treiber lokal oder global vorhanden sein.

Funktionen

Multi-Datenbank, eine Oberfläche

Die meisten Datenbank-MCP-Server zwingen dich dazu, Zugangsdaten bei jeder Sitzung neu zu konfigurieren. Dieser Server nicht. Benannte Verbindungen bleiben in Gruppen gespeichert – erstelle sie einmal, verwende sie immer wieder.

Nachverbindungen funktionieren wie Git-Branches. Du erstellst dev, staging, prod einmal in einer Gruppe, und sie sind immer verfügbar. Der Wechsel erfolgt in Fffffffekt – ein Befehl, null Neukonfiguration:

"Create a group called my-project and add this directory as scope"
"Create a connection called dev with host localhost, database myapp, user admin in my-project"
"Create a read-only connection called analytics pointing to ./data/metrics.db in my-project"
"Switch to dev"               -> queries go to PostgreSQL
"Switch to analytics"         -> queries go to SQLite
"Duplicate dev as dev-readonly with read-only mode"

Gruppenbezogene Verbindungen bedeuten, dass verschiedene Projekte automatisch verschiedene Datenbanken sehen. Arbeitest du an Projekt A? Du siehst die Gruppe und die Verbindungen von Projekt A. Wechselst du in das Verzeichnis von Projekt B, übernimmt sie die Projektgruppe B nativem Standard. Kein manuelles Umschalten, keine Interferenz zwischen Projekten:

"Create a group called frontend with scope /home/user/frontend"
"Create a group called backend with scope /home/user/backend"

Jedes Verzeichnis besitzt damit seine eigene isolierte Verbindungsgruppe.

100 % lokal gespeicherte Zugangsdaten. Jede Verbindung wird als JSON-Datei in ~/.database-mcp/connections/ abgelegt. Passwörter verlassen deinen Rechner nie. Es wird nichts an die Cloud gesendet und nichts in Git committet. Deine Zugangsdaten gehören dir.

Live-Verwaltung. Verbindungen anlegen, duplizieren, umbenennen, testen, exportieren und mitten im Gespräch wechseln. Kein Neustart nötig, kein Bearbeiten von Konfigurationsdaten, kein Kontextverlust.

Sicherheit eingebaut

Rollback-Snapshots

Jede Mutation speichert einen Abzug des Zustands vor der Änderung. Du kannst alles rückgängig machen.

"Show me available rollbacks"
"Rollback the last delete"
  -> "This will INSERT 47 rows back into orders. Confirm?"
  -> Rows restored via reverse SQL

Schema-Introspektion

Drei Detailstufen mit Filterung durch Muster:

"List all tables"                         -> names only (fast)
"Show me the users table with columns"    -> columns + types + nullable
"Full schema for orders including FKs"    -> columns + foreign keys + indexes
"Tables starting with user"              -> pattern: 'user%'

MCP-Ressourcen (db://schema und db://tables/{name}/schema) geben KI-Agenten automatischen Zugriff unweshalb – kein manuelles SQL für tabellenübergreifende Abfragen.

Abfragen mit EXPLAIN und weiterem Abfragen

"Show me all users"
  -> SELECT * FROM users LIMIT 100         <- auto LIMIT

"Show the execution plan for this query"
  -> EXPLAIN ANALYZE with dialect-specific syntax (PostgreSQL/MySQL/SQLite)

Komprimierungsmodi (v0.3+)

SQL-Ergebnisse enthalten oft TEXT / JSON / HTML-Spalten, die mehrere KB pro Zeile groß sein können. KI-Agenten zahlen für jedes Byte, das ins Kontextfenster gelangt. execute_query, execute_mutation und explain_query akzeptieren vier optionale Parameter, die 60-95 % der Tokens einsparen und gleichzeitig Zeilen und Struktur erhalten.

Modi:

• minimal — liefert nur rowCount, executionTimeMs, affectedRows und eine Vorschau der erste Zeile. Ideal für die Bestätigung von INSERT/UPDATE/DELETE, für COUNT-Abfragen und Polling. Sp tr Spar ~90-95 % Tokens.

• normal (Standard) — vollständige Zeilen, aber jede Zelle auf max_cell_bytes gekürzt, mit eine Markierung …(+NB). Behält die Tabellenstruktur bei. Sparent ~60-80 % Tokens bei breiten Zeilen.

• full — die gesamte Ergebnis. Ungetrübten. Verwenden Sie es, wenn Sie den vollständigen Wert jeder Zelle benötigen.

Typische Ersparnis bei SELECT * FROM blog_posts LIMIT 100: Die content-Spalte enthält ~2 KB HTML pro Zeile (~200 KB insgesamt):

Für einen direkten Vergleich mit psql und konkreten Werten sieh dir Native Alternativen unten an.

Volles Ergebnis wiederherstellen: Jede komprimierte Antwort enthält eine call_id. Wenn du die vollständigen Zellen brauchst, ruf run_inspect_last_query({ call_id }) auf — ohne das SQL erneut auszuführen, Dadurch bleiben DB-Last und Seiteneffekte erhalten. Die Ergebnisse werden in einem Objekt RingBuffer (20 Plätze) sowie unter ~/.database-mcp/last-queries/ gespeichert. Die gibt mit 1 Stunden TTL.

// Example: normal (default) response
{
  "call_id": "k3m9a2xp",
  "columns": ["id", "title", "content"],
  "rows": [
    { "id": 1, "title": "Hello", "content": "<h1>Long HTML…(+1847B)" }
  ],
  "rowCount": 1,
  "executionTimeMs": 12,
  "cells_truncated": 1,
  "hint": "1 cell(s) truncated to 500 bytes. Use inspect_last_query({ call_id: \"k3m9a2xp\" }) for full values.",
  "tokens_saved_estimate": 462
}

Native Alternativen: echte Token Sisierung

Wie schneidet dieser MCP im Vergleich zu den nativen Optionen abschneidet, die Claude Code hat, wenn database nicht verfügbar (Bash + psql, sqlite3, mysql CLI etc.).

TL;DR: Im Vergleich zu psql spart execute_query 78 bis 96 % der Kontext-Tokens – je nach Modus – ohne umwiederkehrende Debug-Information. Diesen auf Basis ei echtes Aufruf bei SELECT * FROM blog_posts LIMIT 5 auf einer PostgreSQL-Tabelle mit content-Spalte mit jeweils ~1 KB HTML pro Zeile:

Warum die Zahlen dieser Tabelle von den Angaben im Abschnitt „Compression modes“ weiter oben abweichen: Diese stammen aus einer realen Abfrage mit 5 Zeilen, während die vorherige Tabelle auf ein 100-Zeilen-Ergebnis mit schwerwiegenderem Inhalt extrapoliert. Trend und Größenordnung bleiben gleich.

Anmerkungen:

• Rohausgaben von psql werden mit mehr Zeilen schlechter – JSONB- und lange TEXT-Spalten haben keinen nativen Filter. Die MCP-Zellentrunkierung erhält die Struktur (Zeilenanzahl + Spaltenliste) und reduziert große Zellen mit einem …(+NB)-Marker.

• inspect_last_query liefert das vollständige Ergebnis ohne das SQL erneut auszuführen. Bei psql müsstest du die Abfrage neu ausführen, was wieder DB-CPU kostet und Nebenwirkungen bei RETURNING-Klauseln riskiert.

• Der MCP bietet außerdem Funktionen ohne direkte native Entsprechung: Verbindungsgruppen mit Projektverzeichnis-Scope, automatische Rollback-Snapshots bei Mutationen, Query-History, Schema-Introspection via MCP-Resources sowie Dump/Restore.

• Schema-Kontext wird bei Bedarf ans Ende der Antwort gehängt (Standard bei normal/full: true). Mit include_schema_context: false kann das deaktiviert werden, falls der Agent das Schema bereits kennt.

• Jeder registrierte MCP verursacht feste ~300–600 Token pro Session (aus Instructions + Toolnamen). Üblicher Break-even ist 1 echte Abfrage pro Session.

Dump und Restore

Vollständiges Datenbank-Backup im SQL-Format – nur als Struktur oder mit Daten.

"Dump the database"
  -> Choose: structure only or full
  -> Choose: all tables or specific ones
  -> SQL file saved to .database-mcp/dumps/

"Restore from the last dump"
  -> Lists available dumps, asks for confirmation, executes

Der generierte SQL behandelt DROP TABLE IF EXISTS, FK deaktivieren/aktivieren und Dialekt-spezifische DDL.

Abfrageverlauf

Jede Abfrage wird pro Projekt mit Zeitstempel, Verbindung, Ausführungszeit und Ergebnis-Typ protokolliert.

"What queries did I run today?"
"Show me only mutations"
"History for the prod connection"

Verbindungen exportieren und importieren

"Export all connections"                    -> JSON with masked passwords
"Export with secrets included"             -> JSON with real credentials
"Import these connections: { ... }"        -> creates missing connections

Tool-Referenz

33 Werkzeuge in 8 Kategorien plus 2 MCP-Ressourcen:

Ressourcen: db://schema · db://tables/{tableName}/schema

Tipp: Du musst diese Tools nie direkt aufrufen. Beschreibe einfach, was du möchtest, und die KI wählt das passende Werkzeug.

Speicherorte

Die Speicherung ist bewusst auf zwei Standorte verteilt. Diese Trennung ist gewollt und löst ein echtes Problem: Deine Anmeldedaten gehören dir, deine Projekt-Historie gehört zum Projekt.

Global: ~/.database-mcp/ – Gruppen, Verbindungen, Anmeldedaten und Einstellungen. Liegen in deinem Benutzerverzeichnis. Nie im Projekt, nie in Git, nie mit jemandem geteilt, außer du exportierst sie explizit.

Projektbezogen: {project}/.database-mcp/ – Abfrageverlauf, Rollback-Snapshots und Datenbank-Dumps. Liegen im Projektverzeichnis und werden beim ersten Schreiben automatisch zur .gitignore hinzugefügt.

~/.database-mcp/                          # Global (configurable via DATABASE_MCP_DIR)
├── groups/                               # Connection groups with scopes and defaults
├── connections/                          # Connection configs (credentials, chmod 600)
├── project-conns.json                    # Session-only active connections (cleared on restart)
└── config.json                           # Server config (limits)

{your-project}/.database-mcp/            # Per-project (auto-gitignored)
├── history.json                          # Query history (max 5000)
├── rollbacks.json                        # Pre-mutation snapshots (max 1000)
└── dumps/
    └── {conn}-{timestamp}-{mode}.sql     # Database dumps

Das Ergebnis: Du kannst ein Projekt-Repository frei teilen – Mitwirkende bekommen die Historie und Rollback-Struktur, aber keinerlei Anmeldedaten. Sie erstellen ihre eigenen Verbindungen und Gruppen lokal.

Konfiguration

Konfigurierbar über das Gespräch oder über Umgebungsvariablen:

"Set max rollbacks to 2000"
"Set max history to 10000"

Priorität: Umgebungsvariable > gespeicherte Konfiguration > Standard.

Warnung: Wenn du DATABASE_MCP_DIR auf einen Pfad in einem Git-Repository festlegst, füge .database-mcp/ zu deiner .gitignore hinzu, um zu vermeiden, dass Anmeldedaten in Git mitkommited werden.

Architektur

src/
├── index.ts              # Entry point (StdioServerTransport)
├── server.ts             # createServer() factory
├── tools/                # 33 tool handlers (one file per category)
├── resources/            # MCP Resources (schema auto-discovery)
├── services/             # Business logic
│   ├── connection-manager    # Lazy connect, driver caching
│   ├── schema-introspector   # Multi-dialect introspection (3 detail levels)
│   ├── query-executor        # Read/mutation/explain with safety
│   ├── rollback-manager      # Snapshot capture + reverse SQL
│   ├── history-logger        # Per-project query log
│   └── dump-manager          # Dump/restore (SQL generation)
├── drivers/              # Database adapters (postgres, mysql, sqlite)
├── lib/                  # Types, storage, sanitization
└── utils/                # SQL classifier, parser, formatter

• Null Laufzeitabhängigkeiten außer @modelcontextprotocol/sdk und zod

• Striktes TypeScript – kein any

• Dynamisches Laden der Treiber – import('postgres') / import('mysql2/promise') / import('sql.js') zur Laufzeit

• < 60 KB gebündelt (via tsup)

• Factory-Muster – createServer(storageDir?, projectDir?) für isolierte Testinstanzen

MIT · Erstellt von cocaxcode