dbt CLI

by mammothgrowth

18 stars

218 downloads

Not rated

GitHub

About

An MCP server that wraps the dbt CLI, allowing AI agents to interact with dbt projects.

Details

Author: mammothgrowth
GitHub stars: 18
Downloads: 218
Categories: Database, Other, Infrastructure, Search
Tags: #data-analysis, #sql

- Execute dbt commands through MCP tools
- Supports run, test, compile, ls, debug, deps, seed, show
- Configurable dbt executable path and profiles directory
- Environment variable management for dbt projects
- Command-line interface for direct interaction
- Integration tests against a real dbt project

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name dbt CLI

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

From the repository

Install with Python 3.10+, uv, and dbt CLI. Clone the repository, create a virtual environment, and install dependencies. Use the command-line interface directly or configure the server in an MCP client (e.g., Claude for Desktop) using the provided JSON configuration. All tools require the absolute path to the dbt project directory.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "dbt cli": {
            "dbt-cli-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

McpServers

{
    "dbt-cli-mcp": {
        "command": "uv",
        "args": [
            "venv"
        ]
    }
}

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 --help

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 executable
- ENV_FILE: Path to environment file
- LOG_LEVEL: Logging level
- DBT_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 } } } }

⚠️ IMPORTANT: Absolute Project Path Required ⚠️

When using any tool from this MCP server, youMUSTspecify theFULL ABSOLUTE PATHto your dbt project directory with theproject_dirparameter. 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 thecomplete dbt MCP usage guidefor 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)

{ "models": "customers", "project_dir": "/path/to/dbt/project", "limit": 10 } </use_mcp_tool>

### dbt Profiles Configuration When using the dbt MCP tools, it's important to understand how dbt profiles are handled: 1. 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 2. 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. 3. 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:

yaml jaffle_shop: # This name must match the profile in dbt_project.yml target: dev outputs: dev: type: duckdb path: 'jaffle_shop.duckdb' threads: 24

When 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.py

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-submodulesas 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_duckdb
```

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

Official MCP server for dbt (data build tool) providing integration with dbt Core/Cloud CLI, project metadata discovery, model information, and semantic layer querying capabilities.

Query and analyze data with MotherDuck and local DuckDB

A collection of tools for managing the platform, addressing data quality and reading and writing to Teradata Database.

A read-only MCP server for Avro data sources, powered by the CData JDBC Driver.

Run SQL queries on data in Amazon S3 using AWS Athena.

Interact with Bauplan data tables and run queries.

Production-grade MCP server for Databricks: SQL Warehouses, Jobs API, multi-workspace support.

Visual no-code generator that turns any database into multiple scoped MCP servers — one per access group, with PII masking and fail-closed query scoping built in.

A read-only MCP server by CData that enables LLMs to query live data from EnterpriseDB databases.

A read-only MCP server for MySQL, enabling LLMs to query live data using the CData JDBC Driver.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

⚠️ IMPORTANT: Absolute Project Path Required ⚠️

Install

More like this

Sequential Thinking

Redis

Filesystem

EverArt

Google Drive

Sqlite