Configuration du serveur MCP dbt

Cette note couvre la configuration pratique du serveur local MCP dbt. Si vous choisissez entre local et distant, commencez par là. Si vous avez choisi le local, c’est ici que vous le configurez.

Prérequis

Trois éléments sont nécessaires :

1. uv — le gestionnaire de paquets d’Astral. Le serveur MCP dbt utilise uvx (le lanceur d’outils de uv) pour démarrer sans installation permanente. Si vous avez utilisé npx dans l’écosystème JavaScript, même concept.
2. dbt — Core, Fusion Engine ou Cloud CLI fonctionnent tous. Vous avez besoin du chemin vers l’exécutable.
3. Un projet dbt — un répertoire contenant 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.

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"

Vérifiez avec uv --version.

Trouver Vos Chemins

Vous avez besoin de deux chemins : l’exécutable dbt et votre répertoire de 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

Vérifiez toujours que le serveur démarre avant de le connecter à votre client IA :

export DBT_PROJECT_DIR=/path/to/your/dbt/project
export DBT_PATH=/path/to/your/dbt/executable

uvx dbt-mcp

S’il démarre sans erreurs, appuyez sur Ctrl+C et passez à la configuration. Échecs courants :

• “dbt not found” — DBT_PATH ne pointe pas vers l’exécutable réel. Utilisez which dbt pour le trouver.
• “project not found” — DBT_PROJECT_DIR ne contient pas dbt_project.yml. Vérifiez le chemin.

Configuration

CLI uniquement (sans dbt Cloud)

La configuration minimale vous donne les commandes CLI, la découverte de métadonnées et la lignée :

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

Aucun compte cloud nécessaire. C’est la configuration avec laquelle la plupart des data engineers devraient commencer.

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 nom d’hôte réel :

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

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]

Créez votre token de service sous Account Settings, puis Service Tokens. Accordez les permissions selon vos besoins :

Commencez par Metadata Only. Ajoutez des permissions selon les besoins.

Référence des Variables d’Environnement

Toggles de Fonctionnalité

Ces variables d’environnement désactivent des groupes d’outils spécifiques, ce qui réduit la surcharge de la fenêtre de contexte :

Les toggles de fonctionnalité sont également un mécanisme de sécurité. Définir DISABLE_DBT_CLI=true garantit que l’IA ne peut pas exécuter, construire ou tester contre l’entrepôt connecté — utile quand le serveur est configuré avec des identifiants de production.

Configuration du Client

Claude Code

Le chemin rapide :

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

# Modifier 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 à portée de 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 garde les identifiants hors du contrôle de version :

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

Ce pattern reflète les patterns de variables d’environnement utilisés dans d’autres configurations de serveur MCP — identifiants dans les variables d’environnement, jamais validés dans git.

Claude Desktop

Éditez directement le fichier de configuration :

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

Ajoutez votre configuration de serveur (même JSON que ci-dessus), puis redémarrez Claude Desktop.

Vérifier la Connexion

Après avoir configuré votre client, testez avec une simple requête de métadonnées :

Quels modèles avons-nous dans ce projet ?

Si l’IA retourne une liste de vos modèles dbt, la connexion fonctionne. Si elle ne trouve pas le serveur, vérifiez que uvx est dans votre PATH et que vos variables d’environnement sont correctement définies.

Pour Claude Code spécifiquement, claude mcp list affiche les serveurs connectés et leur état. C’est le moyen le plus rapide de déboguer les problèmes de connexion.