The dbt MCP Server connects your dbt project to AI assistants like Claude Desktop and Claude Code. You type “What customer models do we have?” and get back a list with descriptions. You ask about lineage and see upstream sources and downstream dependencies. You can query your Semantic Layer, run tests, compile SQL, or trigger jobs through conversation.

The value is in avoiding context-switching. Your dbt knowledge stays in your terminal or chat window instead of scattered across documentation tabs and CLI sessions.

Two modes exist: local and remote. The local server runs on your machine with full CLI access (run, build, test, compile) and works without a dbt Cloud account. The remote server is hosted by dbt Labs and needs no installation, but only provides read-only access to metadata and metrics. It requires a dbt Cloud plan.

Most data engineers will want the local server. That’s what this guide covers.

Prerequisites

You need three things:

1. uv package manager from Astral
2. dbt (Core, Fusion Engine, or Cloud CLI all work)
3. A dbt project with a dbt_project.yml file

A dbt Cloud account is optional. You only need it for Semantic Layer queries and job management.

The server uses uvx to run without permanent installation. If you’ve used npx, it works the same way. It keeps your system clean and always pulls the latest version.

Local vs Remote Server

The local server gives you everything: CLI commands (build, run, test, compile), metadata discovery, lineage, and (with dbt Cloud credentials) Semantic Layer queries and job management. You need uv, a dbt installation, and a project directory.

The remote server requires no installation but only offers read-only access. No CLI commands. You need a dbt Cloud plan. This option suits analysts who want to query metrics without touching the codebase.

This guide focuses on the local server.

Available Tools

The server exposes these tools to the AI assistant.

dbt CLI Commands (Local Only)

Semantic Layer Tools

Metadata Discovery Tools

Admin API Tools (dbt Cloud)

Installation

Install uv

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Run uv --version to verify it worked.

Find Your dbt Paths

You need two paths: where dbt lives, and where your project lives.

# macOS/Linux
which dbt
# Windows
where dbt
# Example output: C:\Python39\Scripts\dbt.exe

Your project directory is wherever dbt_project.yml lives (e.g., /Users/yourname/projects/analytics).

Test Before Configuring

Make sure it works before wiring it up:

# Set environment variables
export DBT_PROJECT_DIR=/path/to/your/dbt/project
export DBT_PATH=/path/to/your/dbt/executable

# Start the server
uvx dbt-mcp

If it starts without errors, press Ctrl+C and move on to configuration. If you see “dbt not found”, double-check DBT_PATH points to the actual executable. If “project not found”, verify DBT_PROJECT_DIR contains your dbt_project.yml.

Configuration

CLI-Only (No dbt Cloud)

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/your/dbt/executable"
      }
    }
  }
}

This gives you CLI commands, metadata discovery, and lineage. No cloud account needed.

With dbt Cloud

Add these credentials for Semantic Layer and job management:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "your-service-token",
        "DBT_ACCOUNT_ID": "123456",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_DEV_ENV_ID": "12346",
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/your/dbt/executable"
      }
    }
  }
}

If your dbt Cloud URL isn’t cloud.getdbt.com, use your actual hostname:

• emea.dbt.com (EMEA region)
• au.dbt.com (Australia region)
• abc123.us1.dbt.com (Enterprise/Partner instance)

Finding Your dbt Cloud IDs

Your dbt Cloud URLs contain the IDs you need:

https://cloud.getdbt.com/deploy/[ACCOUNT_ID]/projects/[PROJECT_ID]/environments/[ENV_ID]

For example:

https://cloud.getdbt.com/deploy/168080/projects/234567/environments/266994
                              ^^^^^^                            ^^^^^^
                           Account ID                      Environment ID

Create your service token under Account Settings → Service Tokens.

Service Token Permissions

Grant permissions based on which features you need:

Minimum setup: Metadata Only

Full access: Metadata Only + Semantic Layer Only + Job Admin

Environment Variables

Feature Toggles

Client Setup

Claude Code

The quick way:

# Add the server
claude mcp add dbt -- uvx dbt-mcp

# Edit to add environment variables
claude mcp edit dbt

The edit command opens a text editor where you add your environment variables.

For teams, a project-scoped config lets you version control the setup:

claude mcp add dbt -s project -- uvx --env-file /path/to/.env dbt-mcp

This creates a .mcp.json file in your project. The .env file looks like:

DBT_PROJECT_DIR=/path/to/your/dbt/project
DBT_PATH=/path/to/your/dbt/executable
DBT_HOST=cloud.getdbt.com
DBT_TOKEN=your-service-token
DBT_ACCOUNT_ID=123456
DBT_PROD_ENV_ID=12345

Claude Desktop

Edit the config file directly. Find it at:

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

Add your server:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/Users/yourname/projects/analytics",
        "DBT_PATH": "/opt/homebrew/bin/dbt"
      }
    }
  }
}

Restart Claude Desktop after saving.

Example Prompts

Data Discovery

What models do we have in the marts layer?

Show me all sources and their freshness status.

What are the columns in the mrt__sales__customers model?

Show me the lineage for the mrt__sales__orders model.

What models depend on base__shopify__orders?

What are the upstream sources for the revenue metric?

Semantic Layer (Requires dbt Cloud)

Query monthly revenue by region for last quarter.

What dimensions are available for the customer_lifetime_value metric?

Show me the top 10 customers by total order value.

Development

Run tests on the base models.

Compile the SQL for base__shopify__orders and show me the result.

What errors occurred in the last failed run?

Job Management (dbt Cloud)

List all scheduled jobs in the project.

Trigger the daily refresh job.

What's the status of the currently running job?

Watch Out For

CLI Commands Modify Data

Commands like run and build materialize models in your warehouse. If you’re connected to production credentials, you can change production data. Start with a development profile. For production deployments, set DISABLE_DBT_CLI=true.

Copilot Credits

The text_to_sql tool consumes dbt Copilot credits if your plan includes it. Watch your usage.

Remote Server Limitations

The remote server can’t run CLI commands. No run, build, or test. If you need those, use the local server.

Enterprise OAuth

If you’re using OAuth authentication instead of service tokens, dbt MCP requires static subdomains. Check with your dbt Cloud admin for the correct hostname.

Still Experimental

dbt Labs marks this as experimental. The API may change. The #tools-dbt-mcp channel in dbt Community Slack is where to go for updates and help.