Berth -- Datenbank-MCP-Server

License: MIT

Ein sicherer Liegeplatz für Ihre Daten -- Datenbankzugriff für KI-Tools.

Berth ist ein Model Context Protocol-Server, der KI-Assistenten einen sicheren, strukturierten Zugriff auf PostgreSQL-, SQLite- und MySQL-Datenbanken ermöglicht. Er stellt 13 Tools zur Verfügung, um Schemata zu untersuchen, Abfragen auszuführen, Daten zu verwalten, Migrationen zu generieren und Backups durchzuführen – alles gesteuert durch ein 3-stufiges Sicherheitsmodell, das versehentliche Schäden verhindert.

Sicherheitsmodell

Berth erzwingt drei Betriebsmodi, die steuern, welches SQL zulässig ist:

Modus	Standard	Erlaubt	Blockiert
read-only	Ja	`SELECT`, `EXPLAIN`	Alle Schreibvorgänge
write	Nein	`INSERT`, `UPDATE`, `DELETE`, `CREATE`	`DROP`, `TRUNCATE`, `ALTER DROP`, `DELETE` ohne `WHERE`
admin	Nein	Alles	Destruktive Operationen erfordern ein Bestätigungs-Token (60s Gültigkeit)

Der Server startet im read-only-Modus. Schreib- und Admin-Modi müssen explizit aktiviert werden. Destruktive Operationen im Admin-Modus generieren ein einmaliges Bestätigungs-Token, das nach 60 Sekunden abläuft – die KI muss das Token zurückgeben, um die Absicht zu bestätigen.

Tools

Tool	Beschreibung	Wichtige Parameter
`health`	Server-Gesundheitsprüfung	--
`db_connect`	Verbindung zu einer Datenbank herstellen	`dsn` (Verbindungszeichenfolge)
`db_query`	Führt eine SELECT-Abfrage aus (fügt automatisch LIMIT 1000 hinzu)	`connection_id`, `sql`
`db_execute`	Führt INSERT/UPDATE/DELETE aus (beachtet Sicherheitsmodus)	`connection_id`, `sql`, `confirmation_token`
`db_schema`	Listet Tabellen, Views und Indizes auf	`connection_id`
`db_describe`	Spaltendetails für eine Tabelle	`connection_id`, `table`
`db_relationships`	Fremdschlüsselbeziehungen	`connection_id`, `table` (optional)
`db_size`	Datenbank- und Tabellengrößen	`connection_id`
`db_active_queries`	Derzeit laufende Abfragen (nur PostgreSQL)	`connection_id`
`db_explain`	Führt EXPLAIN ANALYZE für eine Abfrage aus	`connection_id`, `sql`
`generate_migration`	Generiert Migrations-SQL durch Vergleich von Schemata	`connection_id` + `target_sql` oder `from_connection` + `to_connection`
`db_backup`	Erstellt ein Datenbank-Backup	`connection_id`, `output_path`
`db_restore`	Wiederherstellung aus Backup (Admin-Modus + Bestätigungs-Token)	`connection_id`, `input_path`, `confirmation_token`

Schema-Migrationen

Das Tool generate_migration vergleicht zwei Schemata und erstellt dialektspezifisches SQL, um von einem zum anderen zu migrieren. Es gibt zwei Betriebsmodi:

Modus 1 — Live-Datenbank vs. Ziel-DDL:

Geben Sie connection_id (eine aktive Verbindung) und target_sql (CREATE TABLE-Anweisungen, die das gewünschte Schema beschreiben) an. Berth untersucht die Live-Datenbank und vergleicht sie mit dem geparsten Ziel.

Modus 2 — Zwei Live-Datenbanken:

Geben Sie from_connection und to_connection (zwei aktive Verbindungs-IDs) an. Berth untersucht beide und generiert die Migration, um die Quelle in das Ziel umzuwandeln.

Was generiert wird:

CREATE TABLE für neue Tabellen
ALTER TABLE ADD COLUMN für neue Spalten
ALTER TABLE ALTER COLUMN / MODIFY COLUMN für Änderungen an Typ, Nullability und Standardwerten
CREATE INDEX / DROP INDEX für Indexänderungen
ADD CONSTRAINT / DROP CONSTRAINT für Fremdschlüsseländerungen
DROP TABLE und DROP COLUMN werden mit Warnungen auskommentiert (Sicherheit geht vor)

Dialekt-Handhabung:

PostgreSQL -- verwendet ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT
MySQL -- verwendet MODIFY COLUMN für alle Spaltenänderungen, DROP INDEX ... ON table
SQLite -- warnt vor nicht unterstützten Operationen und enthält das Tabellen-Neuerstellungsmuster für Änderungen, die dies erfordern (ALTER COLUMN, DROP COLUMN in älteren Versionen, Constraint-Änderungen)

Unterstützte Datenbanken

PostgreSQL -- volle Unterstützung einschließlich pg_stat_activity, EXPLAIN ANALYZE, pg_dump/psql Backup/Wiederherstellung
SQLite -- volle Unterstützung einschließlich PRAGMA-Introspektion, .backup/.restore via sqlite3 CLI
MySQL -- volle Unterstützung einschließlich information_schema-Introspektion, mysqldump/mysql Backup/Wiederherstellung

Installation

Von PyPI:

pip install berth-mcp

Oder in einer isolierten Umgebung:

pipx install berth-mcp

MySQL-Unterstützung erfordert eine optionale Abhängigkeit:

pip install berth-mcp[mysql]

PostgreSQL (asyncpg) und SQLite (aiosqlite) Treiber sind standardmäßig enthalten.

Verwendung

Starten Sie den Server:

berth

Berth kommuniziert über stdio unter Verwendung des MCP-Protokolls. Es ist dafür konzipiert, von einem MCP-Client gestartet zu werden, nicht eigenständig zu laufen.

Claude Code

claude mcp add berth -- berth

Claude Desktop

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

{
  "mcpServers": {
    "berth": {
      "command": "berth",
      "args": []
    }
  }
}

Wenn es in einer virtuellen Umgebung installiert ist, verwenden Sie den vollständigen Pfad:

{
  "mcpServers": {
    "berth": {
      "command": "/path/to/venv/bin/berth",
      "args": []
    }
  }
}

Umgebungsvariablen

Variable	Standard	Beschreibung
`BERTH_BACKUP_DIR`	Aktuelles Arbeitsverzeichnis	Sandbox-Verzeichnis für Backup- und Wiederherstellungspfade. Alle Pfade werden validiert, um innerhalb dieses Verzeichnisses zu bleiben.

Sicherheit

3-stufiges Sicherheitsmodell -- standardmäßig schreibgeschützt, Schreibvorgänge erfordern explizite Zustimmung, destruktive Operationen erfordern Bestätigungs-Token
Bestätigungs-Token -- einmalige UUIDs mit 60-sekündiger Gültigkeit für DROP, TRUNCATE, ALTER DROP und vollständige Tabellen-DELETEs
SQL-Injection-Schutz -- Tabellennamen werden vor der Verwendung in PRAGMA-Anweisungen gegen sqlite_master validiert; durchgehend parametrisierte Abfragen verwendet
Pfad-Traversal-Schutz -- Backup-/Wiederherstellungspfade werden aufgelöst und validiert, um innerhalb von BERTH_BACKUP_DIR zu bleiben; Null-Bytes werden abgelehnt
Passwort-Maskierung -- DSN-Passwörter werden in allen Anzeigeausgaben und Fehlermeldungen maskiert

Entwicklung

git clone https://github.com/seayniclabs/berth.git
cd berth
python -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"
python -m pytest tests/ -q

Integrationstests für PostgreSQL und MySQL erfordern Docker:

docker compose -f tests/docker-compose.test.yml up -d
python -m pytest tests/ -q
docker compose -f tests/docker-compose.test.yml down

Lizenz

MIT

Berth