Skip to main content

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 CLI. For local CLI only (with or without a dbt platform account), see Run dbt locally. To configure or disable specific tools, see the Environment variables reference. Choose OAuth (available for Enterprise and Enterprise+ accounts) or Tokens (more control, better for shared setups).

Prerequisites​

Step 1: Choose your auth method and configure​

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

OAuth is currently available with the local MCP server only. For remote MCP server setups, 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:

Add the config to your MCP client​

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"
      }
    }
  }
}
  1. Save and restart Claude Desktop.

Config file location:

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

Optional: Add local CLI commands​

To also run dbt 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"

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​

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.

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 CLI commands if you added DBT_PROJECT_DIR and DBT_PATH

For the complete tool list, see Available tools.

Looking for local CLI only?

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

Troubleshooting​

 Can't find the uvx executable
 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": { }
    }
  }
}

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
 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 local 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.
 Server not starting
 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 DBT_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
 execute_sql tool not working

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

Cause: execute_sql requires a Personal Access Token (PAT). Service tokens do not work for this tool.

Solution:

  1. Generate a Personal Access Token (PAT) in Account settings → API tokens → Personal tokens.
  2. Use the PAT as your DBT_TOKEN value.
  3. Also ensure DBT_DEV_ENV_ID and DBT_USER_ID are set — these are required for execute_sql.
 Toolset unavailable or showing as disabled
 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
 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

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

 Multi-cell account connection issues
 Multi-cell account connection issues

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

Cause: For multi-cell accounts, the account prefix must be set separately from the host.

Solution:

# ✅ Correct
DBT_HOST=us1.dbt.com
MULTICELL_ACCOUNT_PREFIX=abc123

# ❌ Wrong — don't include the prefix in DBT_HOST
DBT_HOST=abc123.us1.dbt.com

If your full URL is abc123.us1.dbt.com, split it as:

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

For all troubleshooting topics, see MCP troubleshooting.

Next steps​

Was this page helpful?

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

0
Loading