dbt MCP server for AI agents

The dbt MCP server provides a Model Context Protocol implementation for interacting with dbt projects, allowing integration with various AI clients through a standardized interface. It enables AI tools to access dbt functionality, query the Semantic Layer, and interact with dbt Cloud services.

Installation

Prerequisites

Install uv, a Python packaging tool:

# Follow installation instructions at:
# https://docs.astral.sh/uv/getting-started/installation/

Set up configuration:

# Download the example configuration file
curl -O https://raw.githubusercontent.com/dbt-labs/dbt-mcp/main/.env.example

# Rename it to .env
mv .env.example .env

# Edit with your specific settings
nano .env

Configuration Options

Tool Groups

Name	Default	Description
`DISABLE_DBT_CLI`	`false`	Set to `true` to disable dbt Core/Cloud CLI/Fusion tools
`DISABLE_SEMANTIC_LAYER`	`false`	Set to `true` to disable Semantic Layer tools
`DISABLE_DISCOVERY`	`false`	Set to `true` to disable Discovery API tools
`DISABLE_REMOTE`	`true`	Set to `false` to enable remote tools

Discovery, Semantic Layer, and Remote Configuration

Name	Default	Description
`DBT_HOST`	`cloud.getdbt.com`	Your dbt Cloud instance hostname
`MULTICELL_ACCOUNT_PREFIX`	-	Your account prefix if using Multi-cell
`DBT_TOKEN`	-	Personal access token or service token
`DBT_PROD_ENV_ID`	-	Production environment ID

Remote Tools Configuration

Name	Description
`DBT_DEV_ENV_ID`	Development environment ID
`DBT_USER_ID`	Your dbt Cloud user ID

dbt CLI Configuration

Name	Description
`DBT_PROJECT_DIR`	Path to your local dbt project repository
`DBT_PATH`	Path to your dbt executable

Connecting with MCP Clients

General Configuration

Add this to your MCP client's configuration file:

{
  "mcpServers": {
    "dbt-mcp": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/your/.env",
        "dbt-mcp"
      ]
    }
  }
}

Claude Desktop Setup

Create the claude_desktop_config.json file following the instructions at https://modelcontextprotocol.io/quickstart/user
Connect Claude Desktop to the dbt MCP server
For debugging, logs are located at:
- Mac: ~/Library/Logs/Claude
- Windows: %APPDATA%\Claude\logs

VS Code Setup

Open VS Code Settings (Command + Comma)
Select the appropriate tab (Workspace or User)
Navigate to Features → Chat
Ensure "Mcp" is enabled
Click "Edit in settings.json" under "Mcp > Discovery"
Add your server configuration:

{
    "mcp": {
        "inputs": [],
        "servers": {
          "dbt": {
            "command": "uvx",
            "args": [
              "--env-file",
              "/path/to/your/.env",
              "dbt-mcp"
            ]
          }
        }
    }
}

Manage servers using the "MCP: List Servers" command in the Command Palette

Available Tools

dbt CLI Tools

build - Executes models, tests, snapshots, and seeds
compile - Generates SQL without executing
docs - Generates project documentation
ls - Lists project resources
parse - Validates project files
run - Executes models
test - Runs tests
show - Runs queries against the warehouse

Semantic Layer Tools

list_metrics - Retrieves all metrics
get_dimensions - Gets dimensions for metrics
get_entities - Gets entities for metrics
query_metrics - Queries metrics with filters/grouping

Discovery Tools

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
get_model_children - Gets child nodes

Remote Tools

text_to_sql - Generates SQL from natural language
execute_sql - Executes SQL on dbt Cloud's backend

Troubleshooting

If your MCP client can't find uvx, use the full path:

"command": "/full/path/to/uvx"

Find this path with which uvx on Unix systems.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "dbt-mcp" '{"command":"uvx","args":["--env-file","<path-to-.env-file>","dbt-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "dbt-mcp": {
            "command": "uvx",
            "args": [
                "--env-file",
                "<path-to-.env-file>",
                "dbt-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "dbt-mcp": {
            "command": "uvx",
            "args": [
                "--env-file",
                "<path-to-.env-file>",
                "dbt-mcp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect