DBT CLI MCP Server

A Model Context Protocol (MCP) server that wraps the dbt CLI tool, enabling AI coding agents to interact with dbt projects through standardized MCP tools.

Features

Execute dbt commands through MCP tools

Support for all major dbt operations (run, test, compile, etc.)

Command-line interface for direct interaction

Environment variable management for dbt projects

Configurable dbt executable path

Flexible profiles.yml location configuration

Installation

Prerequisites

Python 3.10 or higher

`uv` tool for Python environment management

dbt CLI installed

Setup

Usage

Command Line Interface

The package provides a command-line interface for direct interaction with dbt:

You can also use the module directly:

Command Line Options

`--dbt-path`: Path to dbt executable (default: "dbt")

`--env-file`: Path to environment file (default: ".env")

`--log-level`: Logging level (default: "INFO")

`--profiles-dir`: Path to directory containing profiles.yml file (defaults to project-dir if not specified)

Environment Variables

The server can also be configured using environment variables:

`DBT_PATH`: Path to dbt executable

`ENV_FILE`: Path to environment file

`LOG_LEVEL`: Logging level

`DBT_PROFILES_DIR`: Path to directory containing profiles.yml file

Using with MCP Clients

To use the server with an MCP client like Claude for Desktop, add it to the client's configuration:

IMPORTANT: Absolute Project Path Required

When using any tool from this MCP server, you **MUST** specify the **FULL ABSOLUTE PATH** to your dbt project directory with the `project_dir` parameter. Relative paths will not work correctly.

See the [complete dbt MCP usage guide](docs/dbt_mcp_guide.md) for more detailed instructions and examples.

Available Tools

The server provides the following MCP tools:

`dbt_run`: Run dbt models (requires absolute `project_dir`)

`dbt_test`: Run dbt tests (requires absolute `project_dir`)

`dbt_ls`: List dbt resources (requires absolute `project_dir`)

`dbt_compile`: Compile dbt models (requires absolute `project_dir`)

`dbt_debug`: Debug dbt project setup (requires absolute `project_dir`)

`dbt_deps`: Install dbt package dependencies (requires absolute `project_dir`)

`dbt_seed`: Load CSV files as seed data (requires absolute `project_dir`)

`dbt_show`: Preview model results (requires absolute `project_dir`)

dbt Profiles Configuration

When using the dbt MCP tools, it's important to understand how dbt profiles are handled:

The `project_dir` parameter **MUST** be an absolute path (e.g., `/Users/username/project` not `.`) that points to a directory containing both: - A valid `dbt_project.yml` file - A valid `profiles.yml` file with the profile referenced in the project

The MCP server automatically sets the `DBT_PROFILES_DIR` environment variable to the absolute path of the directory specified in `project_dir`. This tells dbt where to look for the profiles.yml file.

If you encounter a "Could not find profile named 'X'" error, it means either: - The profiles.yml file is missing from the project directory - The profiles.yml file doesn't contain the profile referenced in dbt_project.yml - You provided a relative path instead of an absolute path for `project_dir`

Example of a valid profiles.yml file:

When running commands through the MCP server, ensure your project directory is structured correctly with both configuration files present.

Development

Integration Tests

The project includes integration tests that verify functionality against a real dbt project:

Test Project Setup

The integration tests use the jaffle_shop_duckdb project which is included as a Git submodule in the dbt_integration_tests directory. When you clone the repository with `--recurse-submodules` as mentioned in the Setup section, this will automatically be initialized.

If you need to update the test project to the latest version from the original repository:

If you're seeing errors about missing files in the jaffle_shop_duckdb directory, you may need to initialize the submodule:

License

MIT

dbt CLI