Adrienne Vermorel

dbt MCP Server : guide complet d'installation

2 février 2026

Le dbt MCP Server connecte votre projet dbt aux assistants IA comme Claude Desktop et Claude Code. Vous tapez « Quels modèles clients avons-nous ? » et obtenez une liste avec leurs descriptions. Vous posez une question sur le lineage et voyez les sources en amont et les dépendances en aval. Vous pouvez interroger votre Semantic Layer, lancer des tests, compiler du SQL ou déclencher des jobs par simple conversation.

L’intérêt est d’éviter les changements de contexte. Votre connaissance dbt reste dans votre terminal ou fenêtre de chat au lieu d’être éparpillée entre onglets de documentation et sessions CLI.

Deux modes existent : local et remote. Le serveur local tourne sur votre machine avec un accès complet au CLI (run, build, test, compile) et fonctionne sans compte dbt Cloud. Le serveur remote est hébergé par dbt Labs et ne nécessite aucune installation, mais n’offre qu’un accès en lecture seule aux métadonnées et métriques. Il requiert un plan dbt Cloud.

La plupart des data engineers voudront le serveur local. C’est ce que couvre ce guide.

Prérequis

Trois choses sont nécessaires :

Le gestionnaire de paquets uv d’Astral
dbt (Core, Fusion Engine ou Cloud CLI fonctionnent tous)
Un projet dbt avec un fichier dbt_project.yml

Un compte dbt Cloud est optionnel. Vous n’en avez besoin que pour les requêtes Semantic Layer et la gestion des jobs.

Le serveur utilise uvx pour s’exécuter sans installation permanente. Si vous avez déjà utilisé npx, le principe est le même. Cela garde votre système propre et récupère toujours la dernière version.

Serveur local vs remote

Le serveur local vous donne tout : commandes CLI (build, run, test, compile), découverte des métadonnées, lineage, et (avec des identifiants dbt Cloud) requêtes Semantic Layer et gestion des jobs. Vous avez besoin d’uv, d’une installation dbt et d’un répertoire de projet.

Le serveur remote ne nécessite aucune installation mais n’offre qu’un accès en lecture seule. Pas de commandes CLI. Vous avez besoin d’un plan dbt Cloud. Cette option convient aux analystes qui veulent interroger des métriques sans toucher au code.

Ce guide se concentre sur le serveur local.

Outils disponibles

Le serveur expose ces outils à l’assistant IA.

Commandes CLI dbt (serveur local uniquement)

Outil	Description
`build`	Exécute les modèles, tests, snapshots et seeds dans l’ordre des dépendances
`compile`	Génère le SQL exécutable à partir des modèles sans les exécuter
`docs`	Génère la documentation du projet
`ls`	Liste les ressources du projet
`run`	Exécute les modèles pour les matérialiser dans la base de données
`test`	Lance les tests pour valider les données et l’intégrité des modèles
`show`	Exécute une requête sur le data warehouse

Outils Semantic Layer

Outil	Description
`list_metrics`	Récupère toutes les métriques définies
`get_dimensions`	Obtient les dimensions pour les métriques spécifiées
`query_metrics`	Interroge les métriques avec groupement, tri et filtrage

Outils de découverte des métadonnées

Outil	Description
`get_mart_models`	Récupère tous les modèles mart (couche de présentation)
`get_all_models`	Récupère tous les modèles du projet
`get_model_details`	Obtient le SQL, la description et les colonnes d’un modèle spécifique
`get_model_parents`	Obtient les dépendances en amont d’un modèle
`get_model_children`	Obtient les dépendances en aval d’un modèle
`get_lineage`	Obtient le lineage complet avec une profondeur configurable
`get_all_sources`	Récupère les tables sources avec leurs informations de fraîcheur

Outils Admin API (dbt Cloud)

Outil	Description
`list_jobs`	Liste tous les jobs du projet
`trigger_job_run`	Démarre l’exécution d’un job
`get_job_run_details`	Obtient le statut et les détails d’une exécution de job
`cancel_job_run`	Annule un job en cours d’exécution
`retry_job_run`	Relance un job ayant échoué
`get_job_run_error`	Obtient les détails d’erreur d’une exécution échouée

Installation

Installer uv

macOS / Linux :

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell) :

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Lancez uv --version pour vérifier que cela a fonctionné.

Trouver vos chemins dbt

Vous avez besoin de deux chemins : où se trouve dbt, et où se trouve votre projet.

# macOS/Linux
which dbt
# Windows
where dbt
# Exemple : C:\Python39\Scripts\dbt.exe

Votre répertoire de projet est là où se trouve dbt_project.yml (par exemple, /Users/yourname/projects/analytics).

Tester avant de configurer

Assurez-vous que cela fonctionne avant de brancher le tout :

# Définir les variables d'environnement
export DBT_PROJECT_DIR=/path/to/your/dbt/project
export DBT_PATH=/path/to/your/dbt/executable

# Démarrer le serveur
uvx dbt-mcp

S’il démarre sans erreurs, appuyez sur Ctrl+C et passez à la configuration. Si vous voyez « dbt not found », vérifiez que DBT_PATH pointe bien vers l’exécutable. Si « project not found », vérifiez que DBT_PROJECT_DIR contient votre dbt_project.yml.

Configuration

CLI uniquement (sans dbt Cloud)

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/your/dbt/executable"
      }
    }
  }
}

Cela vous donne les commandes CLI, la découverte des métadonnées et le lineage. Pas besoin de compte cloud.

Avec dbt Cloud

Ajoutez ces identifiants pour le Semantic Layer et la gestion des jobs :

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "your-service-token",
        "DBT_ACCOUNT_ID": "123456",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_DEV_ENV_ID": "12346",
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/your/dbt/executable"
      }
    }
  }
}

Si votre URL dbt Cloud n’est pas cloud.getdbt.com, utilisez votre hostname réel :

emea.dbt.com (région EMEA)
au.dbt.com (région Australie)
abc123.us1.dbt.com (instance Enterprise/Partenaire)

Trouver vos IDs dbt Cloud

Vos URLs dbt Cloud contiennent les IDs dont vous avez besoin :

https://cloud.getdbt.com/deploy/[ACCOUNT_ID]/projects/[PROJECT_ID]/environments/[ENV_ID]

Par exemple :

https://cloud.getdbt.com/deploy/168080/projects/234567/environments/266994
                              ^^^^^^                            ^^^^^^
                           Account ID                      Environment ID

Créez votre service token dans Account Settings → Service Tokens.

Permissions du service token

Accordez les permissions selon les fonctionnalités dont vous avez besoin :

Fonctionnalité	Permission requise
Découverte des métadonnées (`get_model_details`, lineage)	Metadata Only
Requêtes Semantic Layer (`query_metrics`)	Semantic Layer Only
Gestion des jobs (`list_jobs`, `trigger_job_run`)	Job Admin

Configuration minimale : Metadata Only

Accès complet : Metadata Only + Semantic Layer Only + Job Admin

Variables d’environnement

Variable	Requise	Description
`DBT_PROJECT_DIR`	Oui (CLI)	Chemin vers le dossier contenant `dbt_project.yml`
`DBT_PATH`	Oui (CLI)	Chemin complet vers l’exécutable dbt
`DBT_HOST`	Plateforme	Votre hostname dbt Cloud
`DBT_TOKEN`	Plateforme	Service token ou personal access token
`DBT_ACCOUNT_ID`	Plateforme	Votre ID de compte dbt Cloud (requis pour la gestion des jobs)
`DBT_PROD_ENV_ID`	Plateforme	ID de l’environnement de production
`DBT_DEV_ENV_ID`	Plateforme	ID de l’environnement de développement (optionnel)
`DBT_CLI_TIMEOUT`	Optionnel	Timeout des commandes CLI en secondes (défaut : 60)

Toggles de fonctionnalités

Variable	Effet
`DISABLE_DBT_CLI=true`	Désactive tous les outils CLI
`DISABLE_SEMANTIC_LAYER=true`	Désactive les outils Semantic Layer
`DISABLE_SQL=false`	Active les outils SQL (désactivés par défaut)

Configuration du client

Claude Code

La méthode rapide :

# Ajouter le serveur
claude mcp add dbt -- uvx dbt-mcp

# Éditer pour ajouter les variables d'environnement
claude mcp edit dbt

La commande edit ouvre un éditeur de texte où vous ajoutez vos variables d’environnement.

Pour les équipes, une configuration au niveau projet permet de versionner la configuration :

claude mcp add dbt -s project -- uvx --env-file /path/to/.env dbt-mcp

Cela crée un fichier .mcp.json dans votre projet. Le fichier .env ressemble à :

DBT_PROJECT_DIR=/path/to/your/dbt/project
DBT_PATH=/path/to/your/dbt/executable
DBT_HOST=cloud.getdbt.com
DBT_TOKEN=your-service-token
DBT_ACCOUNT_ID=123456
DBT_PROD_ENV_ID=12345

Claude Desktop

Modifiez directement le fichier de configuration. Trouvez-le à :

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

Ajoutez votre serveur :

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/Users/yourname/projects/analytics",
        "DBT_PATH": "/opt/homebrew/bin/dbt"
      }
    }
  }
}

Redémarrez Claude Desktop après avoir enregistré.

Exemples de prompts

Découverte des données

Quels modèles avons-nous dans la couche marts ?

Montre-moi toutes les sources et leur statut de fraîcheur.

Quelles sont les colonnes du modèle mrt__sales__customers ?

Montre-moi le lineage du modèle mrt__sales__orders.

Quels modèles dépendent de base__shopify__orders ?

Quelles sont les sources en amont pour la métrique revenue ?

Semantic Layer (nécessite dbt Cloud)

Requête du revenu mensuel par région pour le dernier trimestre.

Quelles dimensions sont disponibles pour la métrique customer_lifetime_value ?

Montre-moi les 10 meilleurs clients par valeur totale de commande.

Développement

Lance les tests sur les modèles base.

Compile le SQL pour base__shopify__orders et montre-moi le résultat.

Quelles erreurs se sont produites lors de la dernière exécution échouée ?

Gestion des jobs (dbt Cloud)

Liste tous les jobs planifiés du projet.

Déclenche le job de rafraîchissement quotidien.

Quel est le statut du job en cours d'exécution ?

Points d’attention

Les commandes CLI modifient les données

Les commandes comme run et build matérialisent les modèles dans votre warehouse. Si vous êtes connecté avec des identifiants de production, vous pouvez modifier les données de production. Commencez avec un profil de développement. Pour les déploiements en production, définissez DISABLE_DBT_CLI=true.

Crédits Copilot

L’outil text_to_sql consomme des crédits dbt Copilot si votre plan l’inclut. Surveillez votre utilisation.

Limitations du serveur remote

Le serveur remote ne peut pas exécuter de commandes CLI. Pas de run, build ou test. Si vous en avez besoin, utilisez le serveur local.

OAuth Enterprise

Si vous utilisez l’authentification OAuth au lieu de service tokens, dbt MCP nécessite des sous-domaines statiques. Vérifiez auprès de votre admin dbt Cloud le hostname correct.

Encore expérimental

dbt Labs marque ce projet comme expérimental. L’API peut changer. Le canal #tools-dbt-mcp dans le Slack de la communauté dbt est l’endroit où aller pour les mises à jour et l’aide.