dbt MCP server for AI agents

The dbt MCP server implements the Model Context Protocol to provide interaction tools for dbt, enabling AI assistants to access and control dbt functionality through standard interfaces.

Installation

Prerequisites

Before installing the dbt MCP server, you'll need:

uv
Task

Step-by-Step Installation

Clone the repository:

git clone https://github.com/dbt-labs/dbt-mcp.git
cd dbt-mcp

Run the installation task:

task install

Set up environment variables:

cp .env.example .env

Edit the .env file to configure your environment variables according to your needs.

Configuration

Tool Groups Configuration

You can enable or disable specific tool groups with these environment variables:

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

Discovery and Semantic Layer 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`	-	Your personal access token or service token (service token required for Semantic Layer)
`DBT_PROD_ENV_ID`	-	Your dbt Cloud production environment ID

Remote Tools Configuration

Name	Description
`DBT_DEV_ENV_ID`	Your dbt Cloud 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 Core or dbt Cloud CLI executable

Usage with MCP Clients

After installation, you can connect your MCP server to various clients using the following configuration pattern:

{
  "mcpServers": {
    "dbt-mcp": {
      "command": "<path-to-mcp-executable>",
      "args": [
        "run",
        "<path-to-this-directory>/src/dbt_mcp/main.py"
      ]
    }
  }
}

The path to your MCP executable depends on your operating system:

Linux & Mac: <path-to-this-directory>/.venv/bin/mcp
Windows: <path-to-this-directory>/.venv/Scripts/mcp

Claude Desktop Setup

To use with Claude Desktop:

Follow the instructions at https://modelcontextprotocol.io/quickstart/user to create the configuration file
Add the MCP server configuration to your claude_desktop_config.json file

Claude Desktop logs can be found at ~/Library/Logs/Claude on Mac.

Cursor Setup

Open Cursor and go to Settings → Cursor Settings → MCP
Click "Add new global MCP server"
Add the MCP server configuration to the mcp.json file
Verify the connection is active in the MCP tab

VS Code Setup

Open Settings (Command + Comma) and 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 to the settings.json file:

{
    "mcp": {
        "inputs": [],
        "servers": {
          "dbt": {
            "command": "<path-to-mcp-executable>",
            "args": ["run", "<path-to-this-directory>/src/dbt_mcp/main.py"]
          }
        }
    }
}

Manage your MCP servers using:
- The MCP: List Servers command from the Command Palette
- Inline keywords within the settings.json file

Available Tools

dbt CLI Tools

build - Executes models, tests, snapshots, and seeds in dependency order
compile - Generates executable SQL from models, tests, and analyses
docs - Generates documentation for the dbt project
ls - Lists resources in the dbt project
parse - Parses and validates project files
run - Executes models to materialize them in the database
test - Runs tests to validate data and model integrity
show - Runs a query against the data warehouse

Semantic Layer Tools

list_metrics - Retrieves all defined metrics
get_dimensions - Gets dimensions associated with specified metrics
get_entities - Gets entities associated with specified metrics
query_metrics - Queries metrics with optional grouping, ordering, filtering, and limiting

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 of a specific model
get_model_children - Gets children modes of a specific model

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.