Configurer le serveur dbt MCP

Aperçu

Le serveur dbt MCP connecte les outils IA à la CLI de dbt, la Semantic Layer, l'API Discovery et l'API Admin. Cette compétence guide les utilisateurs lors de la configuration avec la bonne configuration pour leur cas d'usage.

Flux de décision

flowchart TB
    start([User wants dbt MCP]) --> q1{Local or Remote?}
    q1 -->|dev workflows,<br>CLI access needed| local[Local Server<br>uvx dbt-mcp]
    q1 -->|consumption only,<br>no local install| remote[Remote Server<br>HTTP endpoint]
    local --> q2{Which client?}
    remote --> q2
    q2 --> claude_desktop[Claude Desktop]
    q2 --> claude_code[Claude Code]
    q2 --> cursor[Cursor]
    q2 --> vscode[VS Code]
    claude_desktop --> config[Generate config<br>+ test setup]
    claude_code --> config
    cursor --> config
    vscode --> config

Questions à poser

1. Type de serveur

Demandez : « Souhaitez-vous utiliser le serveur dbt MCP local ou distant ? »

2. Client MCP

Demandez : « Quel client MCP utilisez-vous ? »

• Claude Desktop
• Claude Code (CLI)
• Cursor
• VS Code

3. Cas d'usage (serveur local uniquement)

Demandez : « Quel est votre cas d'usage ? »

4. Outils à activer

Demandez : « Quels outils souhaitez-vous activer ? » (afficher les valeurs par défaut)

Conditions préalables

Serveur local

1. Installer uv : https://docs.astral.sh/uv/getting-started/installation/
2. Avoir un projet dbt (pour les commandes CLI)
3. Trouver les chemins :
   • DBT_PROJECT_DIR : Dossier contenant dbt_project.yml
     • macOS/Linux : pwd depuis le dossier du projet
     • Windows : Chemin complet avec des barres obliques (p. ex. C:/Users/name/project)
   • DBT_PATH : Chemin vers l'exécutable dbt
     • macOS/Linux : which dbt
     • Windows : where dbt

Serveur distant

1. Compte dbt Cloud avec les fonctionnalités IA activées
2. ID d'environnement de production (depuis la page Orchestration)
3. Token d'accès personnel ou token de service

Consultez How to Find Your Credentials pour obtenir des conseils détaillés sur l'obtention des tokens et des ID.

Sécurité des identifiants

• Utilisez toujours les références de variables d'environnement (p. ex. ${DBT_TOKEN}) plutôt que les valeurs de token littérales dans les fichiers de configuration qui pourraient être validés dans le contrôle de version
• N'enregistrez, n'affichez et n'écoutez jamais les valeurs de token dans la sortie du terminal
• Lors de l'utilisation de fichiers .env, assurez-vous qu'ils sont ajoutés à .gitignore pour éviter les validations accidentelles
• Recommandez aux utilisateurs de renouveler régulièrement les tokens et d'utiliser l'ensemble minimum de permissions requis

Modèles de configuration

Serveur local - CLI uniquement

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

Serveur local - Plateforme + CLI (OAuth)

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "https://your-subdomain.us1.dbt.com",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

Serveur local - Plateforme + CLI (authentification par token)

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "${DBT_TOKEN}",
        "DBT_ACCOUNT_ID": "${DBT_ACCOUNT_ID}",
        "DBT_PROD_ENV_ID": "${DBT_PROD_ENV_ID}",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

Serveur local - Utiliser un fichier .env

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["--env-file", "/path/to/.env", "dbt-mcp"]
    }
  }
}

Contenu du fichier .env :

DBT_HOST=cloud.getdbt.com
DBT_TOKEN=<set-via-env-or-secret-manager>
DBT_ACCOUNT_ID=<your-account-id>
DBT_PROD_ENV_ID=<your-prod-env-id>
DBT_DEV_ENV_ID=<your-dev-env-id>
DBT_USER_ID=<your-user-id>
DBT_PROJECT_DIR=/path/to/project
DBT_PATH=/path/to/dbt

Serveur distant

{
  "mcpServers": {
    "dbt": {
      "url": "https://cloud.getdbt.com/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token ${DBT_TOKEN}",
        "x-dbt-prod-environment-id": "${DBT_PROD_ENV_ID}"
      }
    }
  }
}

En-têtes supplémentaires pour les outils SQL/Fusion :

{
  "headers": {
    "Authorization": "Token ${DBT_TOKEN}",
    "x-dbt-prod-environment-id": "${DBT_PROD_ENV_ID}",
    "x-dbt-dev-environment-id": "${DBT_DEV_ENV_ID}",
    "x-dbt-user-id": "${DBT_USER_ID}"
  }
}

Configuration spécifique aux clients

Claude Desktop

1. Cliquez sur le menu Claude dans la barre de menu système (pas dans l'application)
2. Sélectionnez Settings...
3. Allez à l'onglet Developer
4. Cliquez sur Edit Config
5. Ajoutez la configuration JSON
6. Enregistrez et redémarrez Claude Desktop
7. Vérifiez : Recherchez l'indicateur du serveur MCP en bas à droite de la zone de saisie

Emplacement de la configuration :

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

Claude Code (CLI)

Exécutez :

claude mcp add dbt -s user -- uvx dbt-mcp

Cela ajoute le serveur à votre portée utilisateur/configuration (sur ce système : ~/.claude.json).

Pour une configuration spécifique au projet, exécutez :

claude mcp add dbt -s project -- uvx dbt-mcp

Cela ajoute le serveur à .mcp.json dans la racine de votre projet.

Alternativement, vous pouvez utiliser la configuration manuelle ci-dessous.

Configuration manuelle : Modifiez ~/.claude.json (portée utilisateur) ou créez .mcp.json (portée projet) dans la racine de votre projet :

• ~/.claude.json : Global sur tous les projets
• .mcp.json : Spécifique au projet, peut être validé dans le contrôle de version pour le partage d'équipe. Si vous utilisez l'authentification par token, utilisez les références de variables d'environnement — ne validez jamais les tokens littéraux.

Pour les configurations dbt spécifiques au projet, utilisez .mcp.json afin que votre équipe partage la même configuration.

Une fois la configuration créée, assurez-vous d'ajouter la configuration JSON sous la clé mcpServers.

Cursor

1. Ouvrez Cursor menu → Settings → Cursor Settings → MCP
2. Ajoutez la configuration JSON
3. Mettez à jour les chemins et les identifiants
4. Enregistrez

VS Code

1. Ouvrez Command Palette (Cmd/Ctrl + Shift + P)
2. Exécutez "MCP: Open User Configuration" (ou Workspace pour une portée spécifique au projet)
3. Ajoutez la configuration JSON (note : VS Code utilise servers et non mcpServers) :

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

4. Ouvrez Settings → Features → Chat → Activez MCP
5. Vérifiez : Exécutez "MCP: List Servers" depuis la Command Palette

Utilisateurs WSL : Configurez dans les paramètres distants, pas dans les paramètres utilisateur locaux :

• Exécutez "Preferences: Open Remote Settings" depuis la Command Palette
• Utilisez les chemins Linux complets (p. ex. /home/user/project, pas les chemins Windows)

Étapes de vérification

Tester la configuration du serveur local

Recommandé : Utiliser un fichier .env

1. Créez un fichier .env dans votre répertoire racine du projet et ajoutez les variables d'environnement minimales pour les outils CLI :

   DBT_PROJECT_DIR=/path/to/project
   DBT_PATH=/path/to/dbt

2. Testez le serveur :

   uvx --env-file .env dbt-mcp

Alternative : Variables d'environnement

# Test temporaire (les variables ne durent que pour cette session)
export DBT_PROJECT_DIR=/path/to/project
export DBT_PATH=/path/to/dbt
uvx dbt-mcp

Pas d'erreurs = configuration réussie.

Vérifier dans le client

Après la configuration, demandez à l'IA :

• « What dbt tools do you have access to? » (Quels outils dbt avez-vous accès ?)
• « List my dbt metrics » (Lister mes métriques dbt) (si Semantic Layer activée)
• « Show my dbt models » (Afficher mes modèles dbt) (si Discovery activée)

Consultez Troubleshooting pour les problèmes courants et les corrections.

Consultez Environment Variable Reference pour la liste complète des variables prises en charge.