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.
- 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
- Python 3.10 or higher
uvtool 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]"The package provides a command-line interface for direct interaction with dbt:
# Run dbt models
dbt-mcp run --models customers --project-dir /path/to/project
# Run dbt models with a custom profiles directory
dbt-mcp run --models customers --project-dir /path/to/project --profiles-dir /path/to/profiles
# List dbt resources
dbt-mcp ls --resource-type model --output-format json
# Run dbt tests
dbt-mcp test --project-dir /path/to/project
# Get help
dbt-mcp --help
dbt-mcp run --helpYou can also use the module directly:
python -m src.cli run --models customers --project-dir /path/to/project--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)
The server can also be configured using environment variables:
DBT_PATH: Path to dbt executableENV_FILE: Path to environment fileLOG_LEVEL: Logging levelDBT_PROFILES_DIR: Path to directory containing profiles.yml file
To use the server with an MCP client like Claude for Desktop, add it to the client's configuration:
{
"mcpServers": {
"dbt": {
"command": "uv",
"args": ["--directory", "/path/to/dbt-cli-mcp", "run", "src/server.py"],
"env": {
"DBT_PATH": "/absolute/path/to/dbt",
"ENV_FILE": ".env"
// You can also set DBT_PROFILES_DIR here for a server-wide default
}
}
}
}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.
// ❌ INCORRECT - Will NOT work
{
"project_dir": "."
}
// ✅ CORRECT - Will work
{
"project_dir": "/Users/username/path/to/your/dbt/project"
}See the complete dbt MCP usage guide for more detailed instructions and examples.
The server provides the following MCP tools:
dbt_run: Run dbt models (requires absoluteproject_dir)dbt_test: Run dbt tests (requires absoluteproject_dir)dbt_ls: List dbt resources (requires absoluteproject_dir)dbt_compile: Compile dbt models (requires absoluteproject_dir)dbt_debug: Debug dbt project setup (requires absoluteproject_dir)dbt_deps: Install dbt package dependencies (requires absoluteproject_dir)dbt_seed: Load CSV files as seed data (requires absoluteproject_dir)dbt_show: Preview model results (requires absoluteproject_dir)
When using the dbt MCP tools, it's important to understand how dbt profiles are handled:
-
The
project_dirparameter MUST be an absolute path (e.g.,/Users/username/projectnot.) that points to a directory containing both:- A valid
dbt_project.ymlfile - A valid
profiles.ymlfile with the profile referenced in the project
- A valid
-
The MCP server automatically sets the
DBT_PROFILES_DIRenvironment variable to the absolute path of the directory specified inproject_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:
jaffle_shop: # This name must match the profile in dbt_project.yml
target: dev
outputs:
dev:
type: duckdb
path: 'jaffle_shop.duckdb'
threads: 24When running commands through the MCP server, ensure your project directory is structured correctly with both configuration files present.
The project includes integration tests that verify functionality against a real dbt project:
# Run all integration tests
python integration_tests/run_all.py
# Run a specific integration test
python integration_tests/test_dbt_run.pyThe 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:
git submodule update --remote dbt_integration_tests/jaffle_shop_duckdbIf you're seeing errors about missing files in the jaffle_shop_duckdb directory, you may need to initialize the submodule:
git submodule update --initMIT