MCP Toolbox for Databases — Installer & Démo en direct

Pourquoi l'utiliser

Fonctionnalités clés

Un seul binaire, plusieurs moteurs : Postgres, MySQL, BigQuery, Spanner, AlloyDB, Cloud SQL, SQLite, MSSQL, Redis, Couchbase, Dgraph, Neo4j
tools.yaml déclaratif — chaque outil est un statement nommé et paramétré, pas une trappe SQL libre
Configs préconstruites (--prebuilt postgres) pour un usage immédiat sans configuration
Connection pooling et auth (IAM, OAuth, API key) gérés centralement, pas dans votre prompt
Transport stdio ou HTTP/SSE — compatible Claude Desktop, Cursor, Codex, IDE, agents personnalisés
Règles d'autorisation par outil — restreignez qui peut appeler les statements destructeurs

Démo en direct

Aperçu en pratique

mcp-toolbox-databases.replay ▶ prêt

0/0

Installer

Choisissez votre 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"
      ]
    }
  }
}

Ouvrez Claude Desktop → Settings → Developer → Edit Config. Redémarrez après avoir enregistré.

~/.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 utilise le même schéma mcpServers que Claude Desktop. La config projet l'emporte sur la 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"
      ]
    }
  }
}

Cliquez sur l'icône MCP Servers dans la barre latérale Cline, puis "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"
      ]
    }
  }
}

Même format que Claude Desktop. Redémarrez Windsurf pour appliquer.

~/.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 utilise un tableau d'objets serveur plutôt qu'une 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"
        ]
      }
    }
  }
}

Ajoutez dans context_servers. Zed recharge à chaud à la sauvegarde.

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

Une seule ligne. Vérifiez avec claude mcp list. Supprimez avec claude mcp remove.

Cas d'usage

Usages concrets : MCP Toolbox for Databases

Comment donner à Claude un accès Postgres de production en lecture seule et en sécurité

👤 Ingénieurs backend / data souhaitant des analytics LLM sans risque d'exfiltration ⏱ ~25 min intermediate

Quand l'utiliser : Vous voulez que Claude réponde à des questions sur une vraie base de données sans outil execute_sql générique pouvant faire un DROP TABLE.

Prérequis

Postgres accessible via une URL libpq — Utilisez un rôle en lecture seule ; jamais l'utilisateur applicatif avec droits d'écriture
Docker ou Go installé — Toolbox est livré comme un seul binaire ; l'image Docker est la plus simple

Déroulement

Lancer Toolbox avec le profil postgres préconstruit

Démarre mcp-toolbox en mode stdio avec --prebuilt postgres et POSTGRES_URL pointant vers le réplica en lecture.✓ Copié

→ Toolbox affiche tools registered: list_tables, describe_table, execute_sql_readonly
Le connecter à Claude Desktop

Ajoute la config docker Toolbox dans claude_desktop_config.json sous mcpServers, puis redémarre Claude.✓ Copié

→ /mcp liste les outils Toolbox — sans erreurs
Poser une vraie question

Toolbox : liste les tables. Puis pour orders, quelle est la valeur médiane des commandes sur les 7 derniers jours ? Montre-moi le SQL exact exécuté.✓ Copié

→ Claude appelle list_tables → describe_table → execute_sql_readonly avec un SELECT (jamais UPDATE/DELETE)

Résultat : Analytics en lecture seule sur de vraies données, sans risque de mutation, avec journal d'audit de chaque requête.

Pièges

Pointé vers l'utilisateur avec droits d'écriture — Claude finit par appeler un outil mutant — Utilisez toujours un rôle avec GRANT SELECT uniquement ; vérifiez avec \du dans psql
Connection pool épuisé lors d'appels agents parallèles — Définissez pool.max_open_conns dans tools.yaml ; la valeur par défaut est conservative

Combiner avec : filesystem · github

Définir un outil analyste écrit à la main avec validation de paramètres

👤 Équipes ne voulant pas de SQL brut, uniquement des requêtes sanctionnées ⏱ ~20 min intermediate

Quand l'utiliser : Vous voulez que Claude réponde à « top 10 clients ce mois-ci » sans qu'il invente ses propres jointures.

Prérequis

Fichier tools.yaml — Créez-le à ~/.mcp-toolbox/tools.yaml

Déroulement

Écrire un outil paramétré

Ajoute un outil top_customers dans tools.yaml : paramètre since: date, statement SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ Copié

→ Toolbox se recharge, expose uniquement top_customers — pas de execute_sql_readonly
Appeler depuis Claude

Utilise top_customers since=2026-04-01 et explique le résultat.✓ Copié

→ Appel d'outil unique avec paramètre de date validé, résultat formaté

Résultat : Surface analytique verrouillée — Claude ne peut exécuter que ce que vous avez déclaré.

Pièges

Oublier de supprimer l'outil execute_sql préconstruit — Retirez --prebuilt ; chargez uniquement votre tools.yaml

Explorer des datasets BigQuery sans écrire de SQL

👤 Analystes sur Google Cloud ⏱ ~20 min intermediate

Quand l'utiliser : Vous avez un projet BigQuery et souhaitez que Claude réponde à des questions dessus avec des garde-fous de coût.

Prérequis

Projet GCP + dataset — Lancez gcloud auth application-default login pour que Toolbox récupère les credentials

Déroulement

Lancer Toolbox avec --prebuilt bigquery

Lance Toolbox --prebuilt bigquery avec PROJECT=my-proj.✓ Copié

→ Outils bq_list_datasets, bq_dry_run, bq_query enregistrés
Toujours faire un dry-run d'abord

Avant d'exécuter une requête, appelle bq_dry_run pour estimer les octets scannés. Si > 1 Go, demande-moi avant de lancer.✓ Copié

→ Estimation du coût affichée avant la requête facturée

Résultat : Réponses BigQuery avec garde-fous de coût — pas de requête surprise à 200 €.

Pièges

Incompatibilité de localisation par défaut (US vs EU) — Définissez la variable d'env BIGQUERY_LOCATION

Interroger plusieurs bases de données depuis une seule session Claude

👤 Ingénieurs déboguant des problèmes inter-sources ⏱ ~30 min advanced

Quand l'utiliser : Les données de commandes sont dans Postgres, les événements dans BigQuery, le cache dans Redis — vous avez besoin d'une corrélation entre les trois.

Prérequis

tools.yaml avec plusieurs sources — Définissez chaque source sous sources: et taguez les outils avec la source

Déroulement

Brancher les trois sources

Ajoute postgres-prod, bq-events, redis-cache comme sources dans tools.yaml. Ajoute 1 à 2 outils par source.✓ Copié

→ Toolbox démarre, toutes les sources marquées saines
Poser une question inter-sources

Pour la commande 12345 : récupère la ligne depuis Postgres, la timeline d'événements depuis BigQuery, et l'état actuel du cache depuis Redis. Réconcilie.✓ Copié

→ Trois appels d'outils en parallèle, une réponse cohérente unique

Résultat : Débogage inter-sources sans trois outils séparés ni sessions SSH.

Pièges

Le health check de source échoue silencieusement — Lancez toolbox validate tools.yaml avant de démarrer

Combiner avec : filesystem

Combinaisons

Associez-le à d'autres MCPs pour un effet X10

mcp-toolbox-databases + filesystem

Récupérer un résultat de requête et l'écrire dans un CSV dans votre espace de travail

Toolbox : top 100 commandes cette semaine. Filesystem : sauvegarde sous /tmp/orders.csv.✓ Copié

mcp-toolbox-databases + github

Ouvrir une PR avec une migration SQL après que Claude a proposé un changement de schema

Toolbox : décris la table orders. GitHub : ouvre une PR ajoutant un index sur customer_id.✓ Copié

Outils

Ce que ce MCP expose

Outil	Entrées	Quand appeler	Coût
list_tables	schema?: str	Première étape d'exploration	1 requête
describe_table	table: str	Avant d'écrire du SQL sur une table inconnue	1 requête
execute_sql_readonly	sql: str	Analytics libres sur le réplica en lecture	1 requête
bq_dry_run	sql: str	BigQuery : toujours avant bq_query	gratuit (dry run)
bq_query	sql: str	Après que le dry run montre un coût acceptable	facturé selon les octets scannés
<votre-outil-personnalisé>	dépend de tools.yaml	Tout ce que vous avez déclaré dans tools.yaml	1 requête

Coût et limites

Coût d'exécution

Quota d'API: Aucun — limité par le plafond de connexions de votre BDD
Tokens par appel: 100–5000 selon la taille du résultat
Monétaire: OSS gratuit ; BDD / cloud sous-jacent facturé normalement
Astuce: Limitez les lignes de résultat dans tools.yaml (ex. LIMIT 200) ; pour BigQuery, passez toujours par bq_dry_run d'abord

Sécurité

Permissions, secrets, portée

Portées minimales : rôle BDD en lecture seule

Stockage des identifiants : Variables d'env ou Google ADC ; Toolbox ne persiste jamais les credentials

Sortie de données : Connexion directe à la BDD — pas de relais tiers. Toolbox est local uniquement.

Ne jamais accorder : DBA DROP/TRUNCATE sur la prod

Mettez toujours la prod derrière un réplica en lecture + rôle lecture seule ; jamais l'utilisateur applicatif avec droits d'écriture

Dépannage

Erreurs courantes et correctifs

connexion refusée / pool épuisé

Augmentez pool.max_open_conns dans tools.yaml ; vérifiez la limite de connexions BDD

Vérifier : psql, lancez SELECT count(*) FROM pg_stat_activity

outil non trouvé

Avec --prebuilt, le nom est par ex. pg_list_tables ; vérifiez avec toolbox list-tools

BigQuery 403 accès refusé

Lancez gcloud auth application-default login et accordez roles/bigquery.dataViewer

Vérifier : bq ls

Erreurs Spanner Cloud SDK

Définissez GOOGLE_APPLICATION_CREDENTIALS vers un JSON de compte de service

Alternatives

MCP Toolbox for Databases vs autres

Alternative	Quand l'utiliser	Compromis
DBHub	Vous voulez un seul binaire sans dépendances couvrant Postgres/MySQL/SQL Server	Moins de profondeur BigQuery/Spanner, pas d'IAM Google
Postgres MCP (modelcontextprotocol)	Postgres uniquement, sans config YAML	Moins restrictif — expose execute_sql par défaut
MySQL MCP (benborla)	MySQL uniquement, lecture seule	Mono-moteur, plus simple

Plus

Ressources

📖 Lire le README officiel sur GitHub

🐙 Voir les issues ouvertes

🔍 Parcourir les 400+ serveurs MCP et Skills