Unlock the Power of Your dbt Projects with the dbt MCP Server: A Comprehensive Guide

Are you looking to streamline your dbt workflow and unlock new levels of integration with your favorite data tools? The dbt MCP (Model Context Protocol) Server is your gateway to seamless dbt integration with applications like Claude Desktop, Cursor, and VS Code. This guide will walk you through everything you need to know to get started.

What is the dbt MCP Server and Why Should You Use It?

The MCP Server acts as a bridge, enabling applications to interact directly with your dbt projects. It exposes your dbt models, metrics, and metadata, allowing you to:

• Supercharge your AI-powered coding: Intelligently leverage your dbt context within tools like Claude and Cursor.
• Enhance your VS Code experience: Seamlessly integrate dbt commands and metadata.
• Boost productivity: Automate tasks and access dbt insights directly from your development environment.

Read on to learn how this tool enhances your workflow and simplifies your dbt experience.

Quick Start: Installation in One Line

Ready to dive in? Install or update the dbt MCP Server with this simple command:

/bin/bash -c " $( curl -fsSL https://raw.githubusercontent.com/dbt-labs/dbt-mcp/refs/heads/main/install.sh) "

This script will handle the installation process, and you can run it again later to update to the latest version.

Configuring Your dbt MCP Server: Tailoring it to Your Needs

The dbt MCP Server is highly configurable through environment variables. Here's a breakdown of the key settings:

• DISABLE_DBT_CLI: Disable dbt Core and dbt Cloud CLI objects (set to true).
• DISABLE_SEMANTIC_LAYER: Disable dbt Semantic Layer MCP objects (set to true).
• DISABLE_DISCOVERY: Disable dbt Discovery API MCP objects (set to true).
• DISABLE_REMOTE: Enable remote MCP objects (set to false). Disabled by default for security.
• DBT_HOST: Your dbt Cloud instance hostname (e.g., the Access URL).
• MULTICELL_ACCOUNT_PREFIX: Your Multi-cell account prefix (if applicable).
• DBT_PROD_ENV_ID: Your dbt Cloud production environment ID.
• DBT_DEV_ENV_ID: Your dbt Cloud development environment ID.
• DBT_USER_ID: Your dbt Cloud user ID.
• DBT_TOKEN: Your personal access token or service token (required for the Semantic Layer).
• DBT_PROJECT_DIR: The path to your dbt Project directory.
• DBT_PATH: The path to your dbt Core or dbt Cloud CLI executable (which dbt will show you this).
• DBT_EXECUTABLE_TYPE: Set to core if DBT_PATH points to dbt Core; otherwise, it's assumed to be dbt Cloud CLI.

Proper configuration is essential for the dbt MCP Server to function correctly in each supported environment.

Integrating with MCP Clients: Connecting the Pieces

Once the server is set up, you need to configure your MCP clients (e.g., Claude Desktop, Cursor, VS Code) to connect to it. This typically involves adding a configuration block to the client's settings file. The key is knowing the correct path to the MCP executable.

Here's a general format:

{
  "mcpServers": {
    "dbt": {
      "command": "<path-to-mcp-executable>",
      "args": [
        " run ",
        "<path-to-this-directory>/src/dbt_mcp/main.py"
      ]
    }
  }
}

Replace <path-to-mcp-executable> with the correct path for your operating system:

• Linux & Mac: <path-to-this-directory>/.venv/bin/mcp
• PC: <path-to-this-directory>/.venv/Scripts/mcp

Specific Client Integrations: Tailored Instructions

Let’s get into how to connect the dbt MCP Server to different clients.

Claude Desktop

Follow the instructions provided for creating the claude_desktop_config.json file and establishing the connection. Claude Desktop logs can be found at ~/Library/Logs/Claude on Mac.

Cursor

1. Open Cursor's settings (Settings → Cursor Settings → MCP).
2. Click "Add new global MCP server."
3. Add the configuration from above to the mcp.json file.
4. Verify the connection in the MCP tab.

VS Code

1. Open VS Code's Settings (Command + Comma). Choose "Workspace" or "User" settings based on your needs.
2. Navigate to Features → Chat.
3. Ensure "Mcp" is Enabled.
4. Click "Edit in settings.json" under "Mcp > Discovery."
5. Add your server configuration to the settings.json file:

{
  "mcp": {
    "inputs": [],
    "servers": {
      "dbt": {
        "command": "<path-to-mcp-executable>",
        "args": [ " run ", "<path-to-this-directory>/src/dbt_mcp/main.py"]
        }
      }
    }
  }

Use the correct path for <path-to-mcp-executable> as explained above.

You can manage MCP servers using the "MCP: List Servers" command in the Command Palette (Control + Command + P).

Unleash the Power of the dbt CLI, Semantic Layer and Discovery API

The dbt MCP Server unlocks several tools with the dbt CLI, Semantic Layer, and Discovery API. Be aware that using dbt commands via MCP tooling has the capacity to alter your data models, sources, and warehouse objects. Exercise caution and trust only verified clients.

dbt CLI Commands

The server exposes a range of dbt CLI commands, including:

• build: Executes models, tests, snapshots, and seeds in dependency order.
• compile: Generates executable SQL without running.
• docs: Generates project documentation.
• ls (list): Lists project resources.
• parse: Parses and validates project files.
• run: Executes models.
• test: Runs data and model integrity tests.
• show: Runs a query against the data warehouse.

Semantic Layer Capabilities

Interact with your dbt Semantic Layer metrics through commands like:

• list_metrics: Retrieves all defined metrics.
• get_dimensions: Gets dimensions associated with specified metrics.
• get_entities: Gets entities associated with specified metrics.
• query_metrics: Queries metrics with optional grouping, ordering, filtering, and limiting.

Discovery API Features

Explore your dbt models and relationships with the Discovery API:

• get_mart_models: Gets all mart models.
• get_all_models: Gets all models.
• get_model_details: Gets details for a specific model.
• get_model_parents: Gets parent models of a specific model.

Contributing to the dbt MCP Server

Want to get involved? Check out CONTRIBUTING.md for instructions on contributing to the project.

Conclusion: Elevate Your dbt Workflow Today

The dbt MCP Server provides a powerful way to seamlessly integrate your dbt projects with your favorite data tools. By following this comprehensive guide, you can unlock new levels of productivity, automation, and insight into your data pipelines. Start exploring the possibilities today!