home / mcp / dbt mcp server

DBT MCP Server

Provides an MCP interface to run and manage dbt operations against a dbt project with configurable profiles and environment options.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mammothgrowth-dbt-cli-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/dbt-cli-mcp",
        "run",
        "src/server.py"
      ],
      "env": {
        "DBT_PATH": "/absolute/path/to/dbt",
        "ENV_FILE": ".env",
        "DBT_PROFILES_DIR": "/absolute/path/to/dbt/profiles"
      }
    }
  }
}

This MCP server lets you interact with dbt projects through standardized MCP tools, wrapping the dbt CLI so AI agents and clients can execute dbt commands in a consistent, controllable way. It streamlines running models, tests, and other dbt operations from your preferred MCP client and handles environment and profiles configuration for you.

How to use

Connect to the server from your MCP client by defining an MCP connection that runs locally and exposes dbt operations. You will specify the absolute path to your dbt project and can control which dbt commands to run, such as models, tests, or compilation. Use the tools provided to run, list, debug, and manage dbt resources, all through the same MCP interface.

How to install

# Prerequisites
# - Python 3.10 or higher
# - uv tool for Python environment management
# - dbt CLI installed

# Clone the repository with submodules
git clone --recurse-submodules https://github.com/yourusername/dbt-cli-mcp.git
cd dbt-cli-mcp

# If you already cloned without --recurse-submodules, initialize the submodule
# git submodule update --init

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# For development, install development dependencies
uv pip install -e ".[dev]"

To run the MCP server locally, you will configure your MCP client to connect via a local runtime command described in the configuration example. The runtime uses uv to launch the Python server that exposes the dbt MCP tools.

Configuration and runtime details

MCP clients connect to a local server using a stdio configuration. This server is launched by running a command that starts the Python server script and makes the dbt commands available as MCP tools.

Environment variables that you can set for this server include paths to the dbt executable and an environment file. You can also set a default profiles directory for dbt.

Additional notes

Absolute project path requirement: When you run any tool, you must provide the full absolute path to your dbt project directory in project_dir. Relative paths will not work correctly.

Example: 
- Incorrect: { "project_dir": "." }
- Correct: { "project_dir": "/Users/username/path/to/your/dbt/project" }

Available tools

dbt_run

Execute dbt models and materializations for the specified project and models, using an absolute project_dir.

dbt_test

Run dbt tests to validate models and data quality within the specified project_dir.

dbt_ls

List dbt resources such as models, seeds, and tests for the given project_dir.

dbt_compile

Compile dbt models to check syntax and compiled SQL for the given project_dir.

dbt_debug

Diagnose the dbt project setup and environment against the specified project_dir.

dbt_deps

Install or update dbt package dependencies for the project.

dbt_seed

Load seed data into the database from CSV files for the project_dir.

dbt_show

Preview model results and queries for the given project_dir.