dbt-mcp

MCP.Pizza Chef: dbt-labs

dbt-mcp is a Model Context Protocol server designed to integrate dbt (data build tool) capabilities into LLM-powered workflows. It exposes dbt's functionalities through MCP, allowing models to query, manage, and interact with dbt projects programmatically. This server simplifies automation and real-time context sharing for data transformation, testing, and documentation within dbt environments.

Use This MCP server To

Query dbt project metadata and models programmatically Automate dbt run and test commands via LLM workflows Fetch and summarize dbt documentation and lineage Integrate dbt context into AI-driven data engineering tools Enable real-time dbt project status monitoring through LLMs Trigger dbt model builds based on natural language requests Extract dbt manifest and catalog data for analysis Combine dbt insights with other data sources in AI copilots

README

dbt MCP Server

This MCP (Model Context Protocol) server provides tools to interact with dbt. Read this blog to learn more.

Architecture

architecture diagram of the dbt MCP server

Setup

  1. Clone the repository:
git clone https://github.com/dbt-labs/dbt-mcp.git
cd dbt-mcp
  1. Install uv

  2. Install Task

  3. Run task install

  4. Configure environment variables:

cp .env.example .env

Then edit .env with your specific environment variables (see the Configuration section of the README.md).

Configuration

The MCP server takes the following configuration:

Tool Groups

Name Default Description
DISABLE_DBT_CLI false Set this to true to disable dbt Core and dbt Cloud CLI MCP tools
DISABLE_SEMANTIC_LAYER false Set this to true to disable dbt Semantic Layer MCP objects
DISABLE_DISCOVERY false Set this to true to disable dbt Discovery API MCP objects
DISABLE_REMOTE true Set this to false to enable remote MCP objects

Configuration for Discovery and Semantic Layer

Name Default Description
DBT_HOST cloud.getdbt.com Your dbt Cloud instance hostname. This will look like an Access URL found here. If you are using Multi-cell, do not include the ACCOUNT_PREFIX here
MULTICELL_ACCOUNT_PREFIX - If you are using Multi-cell, set this to your ACCOUNT_PREFIX. If you are not using Multi-cell, do not set this environment variable. You can learn more here
DBT_TOKEN - Your personal access token or service token. Note Service token is required when using the Semantic Layer
DBT_PROD_ENV_ID - Your dbt Cloud production environment ID

Configuration for Remote Tools

Name Description
DBT_DEV_ENV_ID Your dbt Cloud development environment ID
DBT_USER_ID Your dbt Cloud user ID

Configuration for dbt CLI

Name Description
DBT_PROJECT_DIR The path to where the repository of your dbt Project is hosted locally. This should look something like /Users/firstnamelastname/reponame
DBT_PATH The path to your dbt Core or dbt Cloud CLI executable. You can find your dbt executable by running which dbt

Using with MCP Clients

After going through Installation, you can use your server with an MCP client.

This configuration will be added to the respective client's config file. Be sure to replace the sections within <>:

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

<path-to-mcp-executable> depends on your OS:

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

Claude Desktop

Follow these instructions to create the claude_desktop_config.json file and connect.

On Mac, you can find the Claude Desktop logs at ~/Library/Logs/Claude.

Cursor

  1. Open the Cursor menu and select Settings → Cursor Settings → MCP
  2. Click "Add new global MCP server"
  3. Add the config from above to the provided mcp.json file
  4. Verify your connection is active within the MCP tab

Cursor MCP docs here for reference

VS Code

  1. Open the Settings menu (Command + Comma) and select the correct tab atop the page for your use case

    • Workspace - configures the server in the context of your workspace
    • User - configures the server in the context of your user
    • Note for WSL users: If you're using VS Code with WSL, you'll need to configure WSL-specific settings. Run the Preferences: Open Remote Settings command from the Command Palette (F1) or select the Remote tab in the Settings editor. Local User settings are reused in WSL but can be overridden with WSL-specific settings. Configuring MCP servers in the local User settings will not work properly in a WSL environment.
  2. Select Features → Chat

  3. Ensure that "Mcp" is Enabled

mcp-vscode-settings

  1. Click "Edit in settings.json" under "Mcp > Discovery"

  2. Add your server configuration (dbt) to the provided settings.json file as one of the servers:

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

<path-to-mcp-executable> depends on your OS:

  • Linux & Mac: <path-to-this-directory>/.venv/bin/mcp
  • PC: <path-to-this-directory>/.venv/Scripts/mcp
  1. You can start, stop, and configure your MCP servers by:
  • Running the MCP: List Servers command from the Command Palette (Control + Command + P) and selecting the server
  • Utlizing the keywords inline within the settings.json file

inline-management

VS Code MCP docs here for reference

Tools

dbt CLI

  • build - Executes models, tests, snapshots, and seeds in dependency order
  • compile - Generates executable SQL from models, tests, and analyses without running them
  • docs - Generates documentation for the dbt project
  • ls (list) - Lists resources in the dbt project, such as models and tests
  • parse - Parses and validates the project’s files for syntax correctness
  • run - Executes models to materialize them in the database
  • test - Runs tests to validate data and model integrity
  • show - Runs a query against the data warehouse

Allowing your client to utilize dbt commands through this MCP tooling could modify your data models, sources, and warehouse objects. Proceed only if you trust the client and understand the potential impact.

Semantic Layer

  • 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

  • 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 nodes of a specific model
  • get_model_children - Gets children modes of a specific model

Contributing

Read CONTRIBUTING.md for instructions on how to get involved!

dbt-mcp FAQ

How do I install the dbt-mcp server?
Clone the repository, install dependencies like uv and Task, run 'task install', and configure environment variables as per the README.
Can I disable the dbt CLI integration?
Yes, set the environment variable DISABLE_DBT_CLI to true to disable dbt Core CLI usage.
What environment variables are required for configuration?
The server requires variables defined in the .env file, including dbt project paths and optional CLI settings.
Is dbt-mcp compatible with multiple dbt versions?
It supports common dbt versions but check the README for specific compatibility notes.
How does dbt-mcp enhance LLM interactions with dbt?
It exposes structured dbt project data and commands to LLMs, enabling automated and context-aware data workflows.
Can dbt-mcp be used with different LLM providers?
Yes, it is provider-agnostic and works with OpenAI, Anthropic Claude, Google Gemini, and others.
What security considerations are there?
The server scopes access via environment configs and limits CLI usage if disabled, ensuring controlled interaction with dbt projects.
How do I update dbt-mcp to the latest version?
Pull the latest changes from the GitHub repository and rerun the installation steps.