dbt MCP server

The dbt MCP server enables communication between dbt and MCP-compatible AI tools, providing access to dbt commands, Semantic Layer metrics, and Discovery API functionalities through a standardized protocol.

Installation

Prerequisites

1. Install uv, a Python package manager:

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

2. Set up your environment file:

   # Create a .env file based on the template
   cp .env.example .env
   # Edit the .env file with your specific configuration
   

Configuration

Tool Groups Configuration

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

Discovery, Semantic Layer, and Remote Tools Configuration

Name	Default	Description
DBT_HOST	cloud.getdbt.com	Your dbt Cloud instance hostname
MULTICELL_ACCOUNT_PREFIX	-	For Multi-cell users only, set to your account prefix
DBT_TOKEN	-	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 executable (find with which dbt)

Using with MCP Clients

After completing the setup, you can connect the server to various MCP clients using the configuration below. Replace <path-to-.env-file> with the actual path to your .env file:

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

Claude Desktop Setup

1. Create a claude_desktop_config.json file following the instructions at https://modelcontextprotocol.io/quickstart/user
2. Connect your dbt MCP server

Claude Desktop logs can be found at:

• Mac: ~/Library/Logs/Claude
• Windows: %APPDATA%\Claude\logs

Cursor Setup

Use the configuration options detailed above and connect your dbt MCP server through Cursor's interface.

VS Code Setup

1. Open Settings (Command + Comma)
2. Select either Workspace or User tab (WSL users should use Remote Settings)
3. Navigate to Features → Chat
4. Ensure "Mcp" is enabled
5. Click "Edit in settings.json" under "Mcp > Discovery"
6. Add your server configuration:

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

7. Manage your servers through the Command Palette with "MCP: List Servers" or using inline settings.json keywords

Troubleshooting

If an MCP client cannot find uvx, try using the full path:

which uvx  # Find the full path

Then use this full path in your configuration:

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

Available Tools

dbt CLI Tools

• build - Executes models, tests, snapshots, and seeds in dependency order
• compile - Generates executable SQL without running it
• docs - Generates project documentation
• ls - Lists project resources
• parse - Validates project files for syntax
• run - Executes and materializes models
• test - Runs data validation tests
• show - Runs warehouse queries

Note: Using dbt commands can modify your data models and warehouse objects.

Semantic Layer Tools

• list_metrics - Retrieves all defined metrics
• get_dimensions - Gets dimensions for specified metrics
• get_entities - Gets entities for specified metrics
• query_metrics - Queries metrics with optional parameters

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

Remote Tools

• text_to_sql - Generate SQL from natural language
• execute_sql - Execute SQL on dbt Cloud with Semantic Layer support

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