Configuring Dbt MCP Server

Configure dbt MCP Server

Overview

The dbt MCP server connects AI tools to dbt's CLI, Semantic Layer, Discovery API, and Admin API. This skill guides users through setup with the correct configuration for their use case.

Decision Flow

flowchart TB
    start([User wants dbt MCP]) --> q1{Local or Remote?}
    q1 -->|dev workflows,<br>CLI access needed| local[Local Server<br>uvx dbt-mcp]
    q1 -->|consumption only,<br>no local install| remote[Remote Server<br>HTTP endpoint]
    local --> q2{Which client?}
    remote --> q2
    q2 --> claude_desktop[Claude Desktop]
    q2 --> claude_code[Claude Code]
    q2 --> cursor[Cursor]
    q2 --> vscode[VS Code]
    claude_desktop --> config[Generate config<br>+ test setup]
    claude_code --> config
    cursor --> config
    vscode --> config

Questions to Ask

1. Server Type

Ask: "Do you want to use the local or remote dbt MCP server?"

2. MCP Client

Ask: "Which MCP client are you using?"

• Claude Desktop
• Claude Code (CLI)
• Cursor
• VS Code

3. Use Case (Local Server Only)

Ask: "What's your use case?"

4. Tools to Enable

Ask: "Which tools do you want enabled?" (show defaults)

Prerequisites

Local Server

1. Install `uv`: https://docs.astral.sh/uv/getting-started/installation/
2. Have a dbt project (for CLI commands)
3. Find paths:

• DBT_PROJECT_DIR: Folder containing dbt_project.yml
• macOS/Linux: pwd from project folder
• Windows: Full path with forward slashes (e.g., C:/Users/name/project)
• DBT_PATH: Path to dbt executable
• macOS/Linux: which dbt
• Windows: where dbt

Remote Server

1. dbt Cloud account with AI features enabled
2. Production environment ID (from Orchestration page)
3. Personal access token or service token

See How to Find Your Credentials for detailed guidance on obtaining tokens and IDs.

Credential Security

• Always use environment variable references (e.g., ${DBT_TOKEN}) instead of literal token values in configuration files that may be committed to version control
• Never log, display, or echo token values in terminal output
• When using .env files, ensure they are added to .gitignore to prevent accidental commits
• Recommend users rotate tokens regularly and use the minimum required permission set

Configuration Templates

Local Server - CLI Only

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

Local Server - Platform + CLI (OAuth)

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "https://your-subdomain.us1.dbt.com",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

Local Server - Platform + CLI (Token Auth)

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "${DBT_TOKEN}",
        "DBT_ACCOUNT_ID": "${DBT_ACCOUNT_ID}",
        "DBT_PROD_ENV_ID": "${DBT_PROD_ENV_ID}",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

Local Server - Using .env File

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

.env file contents:

DBT_HOST=cloud.getdbt.com
DBT_TOKEN=<set-via-env-or-secret-manager>
DBT_ACCOUNT_ID=<your-account-id>
DBT_PROD_ENV_ID=<your-prod-env-id>
DBT_DEV_ENV_ID=<your-dev-env-id>
DBT_USER_ID=<your-user-id>
DBT_PROJECT_DIR=/path/to/project
DBT_PATH=/path/to/dbt

Remote Server

{
  "mcpServers": {
    "dbt": {
      "url": "https://cloud.getdbt.com/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token ${DBT_TOKEN}",
        "x-dbt-prod-environment-id": "${DBT_PROD_ENV_ID}"
      }
    }
  }
}

Additional headers for SQL/Fusion tools:

{
  "headers": {
    "Authorization": "Token ${DBT_TOKEN}",
    "x-dbt-prod-environment-id": "${DBT_PROD_ENV_ID}",
    "x-dbt-dev-environment-id": "${DBT_DEV_ENV_ID}",
    "x-dbt-user-id": "${DBT_USER_ID}"
  }
}

Client-Specific Setup

Claude Desktop

1. Click Claude menu in system menu bar (not in-app)
2. Select Settings...
3. Go to Developer tab
4. Click Edit Config
5. Add the JSON configuration
6. Save and restart Claude Desktop
7. Verify: Look for MCP server indicator in bottom-right of input box

Config location:

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

Claude Code (CLI)

Run:

claude mcp add dbt -s user -- uvx dbt-mcp

This adds the server to your user scope/config (on this system: ~/.claude.json).

For a project-specific setup, run:

claude mcp add dbt -s project -- uvx dbt-mcp

This adds the server to .mcp.json in your project root.

Alternatively, you can use the manual configuration below.

Manual configuration: Edit ~/.claude.json (user scope) or create .mcp.json (project scope) in your project root:

• ~/.claude.json: Global across all projects