MCP Toolbox for Databases — Installieren & Live-Demo

Warum nutzen

Hauptfunktionen

Ein Binary, viele Engines: Postgres, MySQL, BigQuery, Spanner, AlloyDB, Cloud SQL, SQLite, MSSQL, Redis, Couchbase, Dgraph, Neo4j
Deklaratives tools.yaml — jedes Tool ist ein benanntes, parametrisiertes Statement, kein freies SQL-Einfallstor
Vorgefertigte Konfigurationen (--prebuilt postgres) für sofortigen Zero-Config-Einsatz
Connection Pooling und Auth (IAM, OAuth, API key) zentral verwaltet, nicht im Prompt
Stdio- oder HTTP/SSE-Transport — funktioniert mit Claude Desktop, Cursor, Codex, IDEs und eigenen Agenten
Pro-Tool-Autorisierungsregeln — einschränkbar, wer destruktive Statements aufrufen darf

Live-Demo

In der Praxis

mcp-toolbox-databases.replay ▶ bereit

0/0

Installieren

Wählen Sie Ihren Client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Öffne Claude Desktop → Settings → Developer → Edit Config. Nach dem Speichern neu starten.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cursor nutzt das gleiche mcpServers-Schema wie Claude Desktop. Projektkonfiguration schlägt die globale.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Klicken Sie auf das MCP-Servers-Symbol in der Cline-Seitenleiste, dann "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Gleiche Struktur wie Claude Desktop. Windsurf neu starten zum Übernehmen.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-toolbox-databases",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  ]
}

Continue nutzt ein Array von Serverobjekten statt einer Map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-toolbox-databases": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "TOOLS_FILE=/config/tools.yaml",
          "-v",
          "${HOME}/.mcp-toolbox:/config",
          "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
          "--prebuilt",
          "postgres",
          "--stdio"
        ]
      }
    }
  }
}

In context_servers hinzufügen. Zed lädt beim Speichern neu.

claude mcp add mcp-toolbox-databases -- docker run -i --rm -e TOOLS_FILE=/config/tools.yaml -v ${HOME}/.mcp-toolbox:/config us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt postgres --stdio

Einzeiler. Prüfen mit claude mcp list. Entfernen mit claude mcp remove.

Anwendungsfälle

Praxisnahe Nutzung: MCP Toolbox for Databases

Claude sicheren Read-only-Zugriff auf eine Produktions-Postgres geben

👤 Backend- / Data-Engineers, die LLM-Analysen ohne Exfiltrations-Risiko wollen ⏱ ~25 min intermediate

Wann einsetzen: Claude soll Fragen über eine echte Datenbank beantworten, ohne ein generisches execute_sql-Tool, das TABLE droppen kann.

Voraussetzungen

Postgres via libpq-URL erreichbar — Nur eine Read-only-Rolle verwenden; niemals den schreibbaren App-User
Docker oder Go installiert — Toolbox wird als einzelnes Binary ausgeliefert; Docker-Image ist am einfachsten

Ablauf

Toolbox mit dem vordefinierten Postgres-Profil starten

Starte mcp-toolbox im stdio-Modus mit --prebuilt postgres und POSTGRES_URL, der auf das Read-Replica zeigt.✓ Kopiert

→ Toolbox loggt tools registered: list_tables, describe_table, execute_sql_readonly
In Claude Desktop einbinden

Füge die Toolbox-Docker-Konfiguration unter mcpServers in claude_desktop_config.json hinzu und starte Claude neu.✓ Kopiert

→ /mcp listet Toolbox-Tools — keine Fehler
Eine echte Frage stellen

Toolbox: Tabellen auflisten. Dann für orders: Welcher ist der Median-Bestellwert der letzten 7 Tage? Zeige mir das exakte SQL, das ausgeführt wurde.✓ Kopiert

→ Claude ruft list_tables → describe_table → execute_sql_readonly mit einem SELECT (niemals UPDATE/DELETE) auf

Ergebnis: Read-only-Analysen über echte Daten ohne Mutationsrisiko, mit Audit-Log jeder Query.

Fallstricke

Verbindung mit dem schreibbaren User — Claude ruft irgendwann ein mutierendes Tool auf — Immer eine Rolle mit nur GRANT SELECT verwenden; mit \du in psql prüfen
Connection Pool bei parallelen Agent-Aufrufen erschöpft — pool.max_open_conns in tools.yaml setzen; Standardwert ist konservativ

Kombinieren mit: filesystem · github

Ein handgeschriebenes Analyst-Tool mit Parameter-Validierung definieren

👤 Teams, die kein rohes SQL wollen, nur freigegebene Queries ⏱ ~20 min intermediate

Wann einsetzen: Claude soll die „Top-10-Kunden dieses Monats“ beantworten, aber keine eigenen Joins erfinden.

Voraussetzungen

tools.yaml-Datei — Unter ~/.mcp-toolbox/tools.yaml anlegen

Ablauf

Ein parametrisiertes Tool schreiben

Ein Tool top_customers zu tools.yaml hinzufügen: Parameter since: date, Statement SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ Kopiert

→ Toolbox lädt neu und stellt nur top_customers bereit — kein execute_sql_readonly
Über Claude aufrufen

top_customers seit 2026-04-01 verwenden und das Ergebnis erklären.✓ Kopiert

→ Einzelner Tool-Aufruf mit validiertem Datums-Parameter, formatiertes Ergebnis

Ergebnis: Abgesichertes Analyst-Interface — Claude kann nichts ausführen, was nicht deklariert wurde.

Fallstricke

Vergessen, das vorgefertigte execute_sql-Tool zu entfernen — --prebuilt weglassen; nur die eigene tools.yaml laden

BigQuery-Datasets erkunden ohne SQL zu schreiben

👤 Analysten auf Google Cloud ⏱ ~20 min intermediate

Wann einsetzen: Ein BigQuery-Projekt ist vorhanden, und Claude soll darüber Fragen beantworten mit Kostensicherungen.

Voraussetzungen

GCP-Projekt + Dataset — gcloud auth application-default login ausführen, damit Toolbox die Credentials übernimmt

Ablauf

Toolbox mit --prebuilt bigquery starten

Toolbox --prebuilt bigquery mit PROJECT=my-proj ausführen.✓ Kopiert

→ Tools bq_list_datasets, bq_dry_run, bq_query registriert
Immer zuerst Dry-run

Vor jeder Query bq_dry_run aufrufen, um die gescannten Bytes zu schätzen. Wenn > 1 GB, vorher fragen.✓ Kopiert

→ Kostenschätzung wird vor der kostenpflichtigen Query angezeigt

Ergebnis: BigQuery-Antworten mit Kostensicherungen — keine unerwartete 200-€-Query.

Fallstricke

Standard-Location-Mismatch (US vs. EU) — Env-Variable BIGQUERY_LOCATION setzen

Mehrere Datenbanken aus einer Claude-Session abfragen

👤 Engineers, die cross-store-Probleme debuggen ⏱ ~30 min advanced

Wann einsetzen: Bestelldaten sind in Postgres, Events in BigQuery, Cache in Redis — eine Korrelation über alle drei ist nötig.

Voraussetzungen

tools.yaml mit mehreren Quellen — Jede Quelle unter sources: definieren und Tools mit der Quelle verknüpfen

Ablauf

Alle drei Quellen einbinden

postgres-prod, bq-events, redis-cache als Quellen in tools.yaml hinzufügen. 1–2 Tools pro Quelle hinzufügen.✓ Kopiert

→ Toolbox startet, alle Quellen als gesund markiert
Eine cross-store-Frage stellen

Für Bestellung 12345: Zeile aus Postgres holen, Event-Timeline aus BigQuery und aktuellen Cache-Zustand aus Redis. Abgleichen.✓ Kopiert

→ Drei Tool-Aufrufe aufgefächert, eine kohärente Antwort

Ergebnis: Cross-store-Debugging ohne drei separate Tools oder SSH-Sessions.

Fallstricke

Health-Check einer Quelle schlägt lautlos fehl — toolbox validate tools.yaml vor dem Start ausführen

Kombinieren mit: filesystem

Kombinationen

Mit anderen MCPs für 10-fache Wirkung

mcp-toolbox-databases + filesystem

Ein Query-Ergebnis abrufen und als CSV im Workspace speichern

Toolbox: Top 100 Bestellungen dieser Woche. Filesystem: als /tmp/orders.csv speichern.✓ Kopiert

mcp-toolbox-databases + github

Einen PR mit einer SQL-Migration öffnen, nachdem Claude eine Schema-Änderung vorschlägt

Toolbox: orders-Tabelle beschreiben. GitHub: PR öffnen, der einen Index auf customer_id hinzufügt.✓ Kopiert

Werkzeuge

Was dieses MCP bereitstellt

Werkzeug	Eingaben	Wann aufrufen	Kosten
list_tables	schema?: str	Erster Erkundungsschritt	1 query
describe_table	table: str	Vor dem Schreiben von SQL gegen eine unbekannte Tabelle	1 query
execute_sql_readonly	sql: str	Freie Analysen über das Read-Replica	1 query
bq_dry_run	sql: str	BigQuery: immer vor bq_query	kostenlos (dry run)
bq_query	sql: str	Nachdem Dry-run akzeptable Kosten zeigt	kostenpflichtig pro gescannte Bytes
<your-custom-tool>	abhängig von tools.yaml	Alles, was in tools.yaml deklariert wurde	1 query

Kosten & Limits

Was der Betrieb kostet

API-Kontingent: Keine — begrenzt durch das Connection-Limit der Datenbank
Tokens pro Aufruf: 100–5000 je nach Ergebnisgröße
Kosten in €: Kostenloser Open Source; zugrunde liegende DB / Cloud wird normal abgerechnet
Tipp: Ergebniszeilen in tools.yaml deckeln (z. B. LIMIT 200); für BigQuery immer zuerst bq_dry_run verwenden

Sicherheit

Rechte, Secrets, Reichweite

Minimale Scopes: read-only DB-Rolle

Credential-Speicherung: Env-Variablen oder Google ADC; Toolbox speichert Credentials niemals dauerhaft

Datenabfluss: Direkte DB-Verbindung — kein Drittanbieter-Hop. Toolbox ist nur lokal.

Niemals gewähren: DBA DROP/TRUNCATE auf Produktion

Produktion immer hinter einem Read-Replica + Read-only-Rolle schützen; niemals den schreibbaren App-User verwenden

Fehlerbehebung

Häufige Fehler und Lösungen

connection refused / pool erschöpft

pool.max_open_conns in tools.yaml erhöhen; DB-Connection-Limit prüfen

Prüfen: psql, SELECT count(*) FROM pg_stat_activity ausführen

Tool nicht gefunden

Bei --prebuilt lautet der Tool-Name z. B. pg_list_tables; toolbox list-tools prüfen

BigQuery 403 Zugriff verweigert

gcloud auth application-default login ausführen und roles/bigquery.dataViewer vergeben

Prüfen: bq ls

Spanner Cloud SDK-Fehler

GOOGLE_APPLICATION_CREDENTIALS auf eine Service-Account-JSON setzen

Alternativen

MCP Toolbox for Databases vs. andere

Alternative	Wann stattdessen	Kompromiss
DBHub	Ein einzelnes Zero-Dependency-Binary für Postgres/MySQL/SQL Server gewünscht	Weniger BigQuery/Spanner-Tiefe, kein Google IAM
Postgres MCP (modelcontextprotocol)	Nur Postgres, keine YAML-Konfiguration	Weniger restriktiv — stellt execute_sql standardmäßig bereit
MySQL MCP (benborla)	Nur MySQL, Read-only	Single-Engine, einfacher

Mehr

Ressourcen

📖 Offizielle README auf GitHub lesen

🐙 Offene Issues ansehen

🔍 Alle 400+ MCP-Server und Skills durchsuchen