dbt MCP Server Setup and Configuration

This note covers the practical setup of the dbt MCP local server. If you’re deciding between local and remote, start there. If you’ve decided on local, this is where you configure it.

Prerequisites

You need three things:

1. uv — the package manager from Astral. The dbt MCP server uses uvx (uv’s tool runner) to launch without permanent installation. If you’ve used npx in the JavaScript world, same concept.
2. dbt — Core, Fusion Engine, or Cloud CLI all work. You need the executable path.
3. A dbt project — a directory containing dbt_project.yml.

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

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"

Verify with uv --version.

Find Your Paths

You need two paths: the dbt executable and your project directory.

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

Your project directory is wherever dbt_project.yml lives — for example, /Users/yourname/projects/analytics.

Test Before Configuring

Always verify the server starts before wiring it into your AI client:

export DBT_PROJECT_DIR=/path/to/your/dbt/project
export DBT_PATH=/path/to/your/dbt/executable

uvx dbt-mcp

If it starts without errors, press Ctrl+C and move to configuration. Common failures:

• “dbt not found” — DBT_PATH doesn’t point to the actual executable. Use which dbt to find it.
• “project not found” — DBT_PROJECT_DIR doesn’t contain dbt_project.yml. Check the path.

Configuration

CLI-Only (No dbt Cloud)

The minimal configuration gives you CLI commands, metadata discovery, and lineage:

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

No cloud account needed. This is the config most data engineers should start with.

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]

Create your service token under Account Settings, then Service Tokens. Grant permissions based on what you need:

Start with Metadata Only. Add permissions as needed.

Environment Variable Reference

Feature Toggles

These environment variables disable specific tool groups, which reduces context window overhead:

Feature toggles are also a safety mechanism. Setting DISABLE_DBT_CLI=true ensures the AI cannot run, build, or test against the connected warehouse — useful when the server is configured with production credentials.

Client Setup

Claude Code

The quick path:

# 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 keeps credentials out of version control:

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

This pattern mirrors the environment variable patterns used in other MCP server configurations — credentials in env vars, never committed to git.

Claude Desktop

Edit the config file directly:

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

Add your server configuration (same JSON as above), then restart Claude Desktop.

Verifying the Connection

After configuring your client, test with a simple metadata query:

What models do we have in this project?

If the AI returns a list of your dbt models, the connection is working. If it can’t find the server, check that uvx is on your PATH and that your environment variables are set correctly.

For Claude Code specifically, claude mcp list shows connected servers and their status. This is the fastest way to debug connection issues.