Skip to main content

Connect dbt MCP to dbt platform

Back to guides
dbt MCP
AI
Quickstart
Beginner
Menu

    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