Connect dbt MCP server to dbt platform

This quickstart uses the local MCP server: it runs on your machine using uvx dbt-mcp, connects to your dbt platform for Semantic Layer, Discovery, and SQL, and optionally runs local dbt.

For self-hosted CLI only (with or without a dbt platform account), see Run self-hosted dbt or Run self-hosted dbt Wizard.

To configure or disable specific tools, see the Environment variables reference.

Prerequisites

• Install uv
• A dbt platform account
• For OAuth connections:
  • MCP OAuth is available for Starter, Enterprise, and Enterprise+ plans.

Step 1: Choose your auth method and configure

OAuth

MCP OAuth is available in public beta for Starter, Enterprise, and Enterprise+ accounts.

OAuth is the fastest setup for dbt platform accounts, no tokens to copy or manage. A browser window opens to authenticate the first time you connect.

For OAuth without a self-hosted installation, use the remote MCP server. Remote MCP OAuth is available in public beta for Starter, Enterprise, and Enterprise+ accounts. If your client does not support OAuth or you need token-based access, use token-based authentication.

Static subdomains required

Only accounts with static subdomains (for example, abc123 in abc123.us1.dbt.com) can use OAuth with MCP servers. Follow these instructions to find your account subdomain. If your account does not have a subdomain, contact support for more information.

Find your Access URL

1. Log in to your dbt platform account.
2. Go to Account settings and copy your Access URL (for example, abc123.us1.dbt.com).

Multi-cell and DBT_HOST format

• The DBT_HOST field accepts both abc123.us1.dbt.com and https://abc123.us1.dbt.com.

• If your Access URL is abc123.us1.dbt.com, split it into two variables:

  • DBT_HOST=us1.dbt.com
  • MULTICELL_ACCOUNT_PREFIX=abc123 Don't include the account prefix in DBT_HOST. For more details, see multi-cell configuration examples.

Add the config to your MCP client

Claude Desktop

Option A: Quick install (recommended)

1. Go to the latest dbt MCP release and download dbt-mcp.mcpb.
2. Double-click the file to open it in Claude Desktop.
3. Enter your Access URL as the dbt platform Host.
4. Enable the server.

Option B: Manual config

1. In Claude Desktop, go to Settings → Developer tab → Edit Config.
2. Paste the following configuration, replacing YOUR-ACCESS-URL with your Access URL:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "YOUR-ACCESS-URL"
      }
    }
  }
}

Report incorrect code

3. Save and restart Claude Desktop.

Config file location:

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

Claude Code

Run this command, replacing YOUR-ACCESS-URL with your Access URL:

claude mcp add dbt \
-e DBT_HOST=YOUR-ACCESS-URL \
-- uvx dbt-mcp

Report incorrect code

For example, if your Access URL is abc123.us1.dbt.com:

claude mcp add dbt \
-e DBT_HOST=abc123.us1.dbt.com \
-- uvx dbt-mcp

Report incorrect code

Cursor

Click a link below with Cursor open to auto-configure, then replace the placeholder with your Access URL:

• dbt platform only (OAuth) — platform features only, no CLI
• dbt platform + CLI (OAuth) — platform features + self-hosted dbt CLI commands

After clicking, replace YOUR-ACCESS-URL with your actual Access URL (for example, abc123.us1.dbt.com) and save.

VS Code

1. Open Settings → Features → Chat and ensure MCP is enabled.
2. Open the Command Palette (Ctrl/Cmd + Shift + P) and select MCP: Open User Configuration.
3. Add the following configuration to mcp.json:

VS Code uses "servers", not "mcpServers"

{
  "servers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "YOUR-ACCESS-URL"
      }
    }
  }
}

Report incorrect code

Replace YOUR-ACCESS-URL with your Access URL (for example, abc123.us1.dbt.com) and save.

Optional: Add self-hosted dbt CLI commands

To also run dbt platform CLI commands (dbt run, dbt build, dbt test, and more), add these two variables to your env block:

"DBT_PROJECT_DIR": "/path/to/your/dbt/project",
"DBT_PATH": "/path/to/your/dbt/executable"

Report incorrect code

Find DBT_PATH by running which dbt (macOS/Linux) or where dbt (Windows). DBT_PROJECT_DIR is the folder containing your dbt_project.yml.

Tokens

Token-based auth gives you more control and is better for shared or team setups. You'll need a service token or Personal Access Token (PAT).

Which token should I use?

• PAT (Personal Access Token): Required if you want to use execute_sql. Tied to your user account.
• Service token: Works for all other platform toolsets. Better for shared or team setups.

See Choosing an auth method for full guidance.

Find your paths and IDs

You need the following values. See Finding your IDs for step-by-step instructions.

Variable	Where to find it
DBT_HOST	Your dbt platform hostname, found in Account settings → Access URL
DBT_TOKEN	A service token or PAT from Account settings → API tokens
DBT_PROD_ENV_ID	Your production environment ID, found in Deploy → Environments
DBT_DEV_ENV_ID	Your development environment ID (required for execute_sql)
DBT_USER_ID	Your numeric user ID (required for execute_sql)
DBT_ACCOUNT_ID	Your account ID (required for Admin API tools)

Use values only, not full URLs

These variables expect hostnames or numeric IDs — not full URLs:

# ✅ Correct
DBT_HOST=cloud.getdbt.com            # https://cloud.getdbt.com also works
DBT_PROD_ENV_ID=54321
DBT_USER_ID=123

# ❌ Wrong — IDs must be numeric, not full URLs
DBT_PROD_ENV_ID=https://cloud.getdbt.com/deploy/12345/projects/67890/environments/54321
DBT_USER_ID=https://cloud.getdbt.com/settings/profile

Report incorrect code

Multi-cell accounts

If your Access URL is abc123.us1.dbt.com, split it into two variables:

• DBT_HOST=us1.dbt.com
• MULTICELL_ACCOUNT_PREFIX=abc123

Don't include the account prefix in DBT_HOST. For more details, see multi-cell configuration examples.

Add the config to your MCP client

Use the configuration below, replacing the placeholder values with your IDs from above. Include only the variables you need:

Claude Desktop

1. In Claude Desktop, go to Settings → Developer tab → Edit Config.
2. Paste the following configuration, replacing the placeholder values:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "your-token-here",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_DEV_ENV_ID": "67890",
        "DBT_USER_ID": "123",
        "DBT_ACCOUNT_ID": "99999"
      }
    }
  }
}

Report incorrect code

3. Save and restart Claude Desktop.

Config file location:

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

Claude Code

Run this command, replacing the placeholders with your actual values:

claude mcp add dbt \
-e DBT_HOST=cloud.getdbt.com \
-e DBT_TOKEN=your-token-here \
-e DBT_PROD_ENV_ID=12345 \
-- uvx dbt-mcp

Report incorrect code

Add -e DBT_DEV_ENV_ID=... and -e DBT_USER_ID=... if you use execute_sql; add -e DBT_ACCOUNT_ID=... for Admin API.

Cursor

1. In Cursor, open Settings → MCP → Edit config (or your config file).
2. Paste the following configuration, replacing the placeholder values:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "your-token-here",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_DEV_ENV_ID": "67890",
        "DBT_USER_ID": "123",
        "DBT_ACCOUNT_ID": "99999"
      }
    }
  }
}

Report incorrect code

3. Save the configuration.

VS Code

1. Open Settings → Features → Chat and ensure MCP is enabled.
2. Open the Command Palette (Ctrl/Cmd + Shift + P) and select MCP: Open User Configuration.
3. Add the following configuration to mcp.json:

VS Code uses "servers", not "mcpServers"

{
  "servers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "your-token-here",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_DEV_ENV_ID": "67890",
        "DBT_USER_ID": "123",
        "DBT_ACCOUNT_ID": "99999"
      }
    }
  }
}

Report incorrect code

4. Save mcp.json and restart VS Code.

 Optional: add self-hosted dbt CLI commands

To also run dbt commands (dbt run, dbt build, dbt test, and more), add these two variables to your env block:

"DBT_PROJECT_DIR": "/path/to/your/dbt/project",
"DBT_PATH": "/path/to/your/dbt/executable"

Report incorrect code

Find DBT_PATH by running which dbt (macOS/Linux) or where dbt (Windows). DBT_PROJECT_DIR is the folder containing your dbt_project.yml.

Step 2: Authenticate

OAuth

The first time you connect, dbt MCP opens a browser window to complete OAuth. After signing in, your session is saved and future connections are automatic.

If authentication doesn't start, close your client and run:

• macOS/Linux: rm -f ~/.dbt/mcp.yml ~/.dbt/mcp.lock
• Windows: Remove-Item -Force $env:USERPROFILE\.dbt\mcp.yml, $env:USERPROFILE\.dbt\mcp.lock

Then restart your client.

Tokens

No additional authentication step is needed — your token is already in the configuration. The server connects automatically when your MCP client starts.

Step 3: Test your setup

Ask your AI assistant a data-related question (for example, "What models are in my dbt project?" or "What metrics are defined in my Semantic Layer?"). If dbt MCP is working, the response will use your dbt metadata.

What's available

With the platform setup, your AI assistant can use:

• Semantic Layer queries
• Metadata Discovery (model lineage, test results, source freshness)
• Admin API (trigger jobs, list runs, get artifacts)
• SQL execution and text-to-SQL (requires a PAT)
• All dbt commands if you added DBT_PROJECT_DIR and DBT_PATH

For the complete tool list, see Available tools.

Looking for self-hosted dbt CLI only?

If you only need to run dbt commands locally (with or without a dbt platform account), see Run self-hosted dbt.

Troubleshooting

Can't find the uvx executable

Symptoms: Error messages like Could not connect to MCP server dbt-mcp, Error: spawn uvx ENOENT, or spawn uvx ENOENT in your MCP client.

Cause: Your MCP client (like Claude desktop) can't find uvx in its PATH because it starts with a limited environment.

Solution: Use the full path to uvx in your configuration.

1. Find the full path:

   • macOS/Linux: Run which uvx in Terminal.
   • Windows: Run where uvx in Command Prompt or PowerShell.

2. Replace "command": "uvx" with the full path:

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

Report incorrect code

Example on macOS with Homebrew: "command": "/opt/homebrew/bin/uvx"

For VS Code (mcp.json), the same fix applies — replace uvx with its full path in the command field.

OAuth login not initiating

Symptoms: The OAuth browser window never opens, or authentication appears to hang.

Cause: dbt MCP uses a lock file to avoid repeated authentication. If a previous session left the lock file in place, it can block new authentication attempts.

Solution:

1. Close your MCP client (Claude Desktop, Cursor, VS Code, etc.).
2. Delete the self-hosted dbt MCP config files:
   • macOS/Linux: rm -f ~/.dbt/mcp.yml ~/.dbt/mcp.lock
   • Windows: Remove-Item -Force $env:USERPROFILE\.dbt\mcp.yml, $env:USERPROFILE\.dbt\mcp.lock
3. Restart your client and try connecting again.

If these steps don't resolve the issue, confirm that AI features are enabled on your account. An account admin can enable them in Account settings → Edit → toggle on Enable account access to dbt Wizard features. Refer to Enable dbt Wizard.

Server not starting

Symptoms: The MCP server shows as disconnected or unavailable in your client.

Diagnosis: Check the server logs:

• VS Code: Open the Command Palette (Ctrl/Cmd + Shift + P) → MCP: List Servers → click the dbt server to see detailed logs.
• Claude Desktop: Check ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\logs (Windows).
• All clients: Set DBT_MCP_LOG_LEVEL=DEBUG in your environment variables to get more verbose output.

Common causes:

• Missing or incorrect (Applies to dbt v1.11 and later) DBT_ENGINE_PROJECT_DIR or DBT_PATH — verify the paths exist and are absolute paths.
• Invalid or expired authentication tokens — generate a new token and update your config.
• Missing required environment variables for the toolset you're trying to use — see Tool requirements.

execute_sql tool not working

Symptoms: The execute_sql tool returns an authentication error or is unavailable.

Cause: How you fix this depends on how you connected:

• Remote MCP with OAuth: Sign in through your MCP client when prompted. You don't need a personal access token.
• Remote MCP with token-based auth: You need a personal access token (PAT). Service tokens won't work. You also need x-dbt-dev-environment-id and x-dbt-user-id headers. The user ID must match the user who created the PAT.
• Local MCP: Set DBT_TOKEN to a personal access token (PAT). Service tokens won't work.

Solution:

1. If you use OAuth for remote MCP, confirm you completed sign-in and consent in your MCP client.
2. If you use token-based auth or local MCP, create a personal access token (PAT) in Account settings → API tokens → Personal tokens.
3. For token-based remote MCP, add the PAT to the Authorization header as Token YOUR_PAT. For local MCP, set the PAT as your DBT_TOKEN value.
4. Also ensure DBT_DEV_ENV_ID and DBT_USER_ID are set (local MCP) or x-dbt-dev-environment-id and x-dbt-user-id headers are set (remote MCP). Refer to Finding your IDs for details.

Toolset unavailable or showing as disabled

Symptoms: A toolset (Semantic Layer, Discovery, Admin API) is not available in your AI client even though you've configured credentials.

Cause: Either the required variables are missing, or the toolset has been explicitly disabled.

Solution:

1. Check that all required variables for the toolset are set — see Tool requirements.
2. Check whether you have any DISABLE_* variables set to true that might be turning off the toolset.
3. If you're using enable mode (DBT_MCP_ENABLE_*), make sure the toolset you need is listed.
4. Set DBT_MCP_LOG_LEVEL=DEBUG to see which toolsets are active at startup.

Pasting full URLs instead of IDs

Symptoms: Authentication errors, unexpected behavior, or the server failing to connect to the right environment.

Cause: Environment variables like DBT_PROD_ENV_ID, DBT_USER_ID, and DBT_ACCOUNT_ID expect numeric integers, not full browser URLs.

Solution:

# ✅ Correct
DBT_HOST=cloud.getdbt.com            # https://cloud.getdbt.com also works
DBT_PROD_ENV_ID=54321
DBT_USER_ID=123

# ❌ Wrong — IDs must be numeric, not full URLs
DBT_PROD_ENV_ID=https://cloud.getdbt.com/deploy/12345/projects/67890/environments/54321
DBT_USER_ID=https://cloud.getdbt.com/settings/profile

Report incorrect code

See Finding your IDs for step-by-step instructions.

Multi-cell or static subdomain account connection issues

Symptoms: Connection errors when your account URL includes a prefix (for example, abc123.us1.dbt.com).

Solution (as of v1.14.0): Set DBT_HOST to the full hostname including the prefix. If you're using PAT-based auth, also set DBT_ACCOUNT_ID.

# ✅ Correct
DBT_HOST=abc123.us1.dbt.com
DBT_ACCOUNT_ID=12345  # required for PAT-based auth

Report incorrect code

You no longer need to set MULTICELL_ACCOUNT_PREFIX or DBT_HOST_PREFIX. If you have these set from an older configuration, remove them.

For all troubleshooting topics, see dbt MCP FAQs and troubleshooting.

Next steps

• Run dbt commands locally: see Run self-hosted dbt
• Configure specific toolsets: see the Environment variables reference
• Understand toolset requirements: see Set up self-hosted MCP

Was this page helpful?

Privacy policyCreate a GitHub issue

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.