Integrate Claude with dbt MCP

Claude is an AI assistant from Anthropic with two primary interfaces:

• Claude Code: A terminal/IDE tool for development
• Claude for desktop: A GUI with MCP support for file access and commands as well as basic coding features

Claude Code

You can set up Claude Code with both the local and remote dbt-mcp server. We recommend using the local dbt-mcp for more developer-focused workloads. See the About MCP page for more more information about local and remote server features.

Set up with local dbt MCP server

Prerequisites:

• Complete the local MCP setup.
• Know your configuration method (OAuth or environment variables)

Claude Code scopes

By default, the MCP server is installed in the "local" scope, meaning that it will be active for Claude Code sessions in the current directory for the user who installed it.

It is also possible to install the MCP server:

• In the "user" scope, to have it installed for all Claude Code sessions, independently of the directory used
• In the "project" scope, to create a config file that can be version controlled so that all developers of the same project can have the MCP server already installed

To install it in the project scope, run the following and commit the .mcp.json file. Be sure to use an env var file path that is the same for all users.

claude mcp add dbt -s project -- uvx --env-file <path-to-.env-file> dbt-mcp

For more information on scopes, refer to Understanding MCP server scopes.

Claude Code OAuth or environment variables setup

The recommended method is to configure environment variables directly in Claude Code's configuration file without needing a separate .env file:

1. Add the MCP server:

claude mcp add dbt -- uvx dbt-mcp

2. Open the configuration editor:

claude mcp edit dbt

3. In the configuration editor, add your environment variables based on your use case:

CLI only

For dbt Core or Fusion only (no dbt platform):

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

OAuth with dbt platform

For OAuth authentication (requires static subdomain):

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

Using an .env file

If you prefer to manage environment variables in a separate file:

claude mcp add dbt -- uvx --env-file <path-to-.env-file> dbt-mcp

Replace <path-to-.env-file> with the full path to your .env file.

Claude Desktop

Static subdomains required

Only accounts with static subdomains (for example, abc123.us1.dbt.com) can use OAuth with MCP servers. All accounts are in the process of being migrated to static subdomains by December 2025. Contact support for more information.

1. Go to the latest dbt MCP release here and download the dbt-mcp.mcpb file.
2. After this is downloaded, double-click on this file to open it in Claude Desktop.
3. Follow the directions to set the dbt Platform Host. You can find this in dbt platform by navigating to Dashboard, then Settings.
4. Enable the server in Claude Desktop.
5. Ask Claude a data-related question and observe dbt MCP being utilized.

Advanced configuration with Claude Desktop

1. Go to the Claude settings and select Settings….

2. In the Settings window, navigate to the Developer tab in the left sidebar. This section contains options for configuring MCP servers and other developer features.

3. Click the Edit Config button and open the configuration file with a text editor.

4. Add your server configuration based on your use case. Choose the correct JSON structure from the following options:

    Local MCP with OAuth

   Local MCP with dbt platform authentication EnterpriseEnterprise +

   Configuration for users who want seamless OAuth authentication with the dbt platform

   dbt platform only

   This option is for users who only want dbt platform features (Discovery API, Semantic Layer, job management) without local CLI commands.

   When you use only the dbt platform, the CLI tools are automatically disabled. You can find the DBT_HOST field value in your dbt platform account information under Access URLs.

   {
     "mcpServers": {
       "dbt": {
         "command": "uvx",
         "args": ["dbt-mcp"],
         "env": {
           "DBT_HOST": "https://<your-dbt-host-with-custom-subdomain>",
         }
       }
     }
   }

   Note: Replace <your-dbt-host-with-custom-subdomain> with your actual host (for example, abc123.us1.dbt.com). This enables OAuth authentication without requiring local dbt installation.

   dbt platform + CLI

   This option is for users who want both dbt CLI commands and dbt platform features (Discovery API, Semantic Layer, job management).

   The DBT_PROJECT_DIR and DBT_PATH fields are required for CLI access. You can find the DBT_HOST field value in your dbt platform account information under Access URLs.

   {
     "mcpServers": {
       "dbt": {
         "command": "uvx",
         "args": ["dbt-mcp"],
         "env": {
           "DBT_HOST": "https://<your-dbt-host-with-custom-subdomain>",
           "DBT_PROJECT_DIR": "/path/to/project",
           "DBT_PATH": "/path/to/dbt/executable"
         }
       }
     }
   }

   Note: Replace <your-dbt-host-with-custom-subdomain> with your actual host (for example, https://abc123.us1.dbt.com). This enables OAuth authentication.

    Local MCP (CLI only)

   Local configuration for users who only want to use dbt CLI commands with dbt Core or Fusion

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

   Finding your paths:

   • DBT_PROJECT_DIR: Full path to the folder containing your dbt_project.yml file
   • DBT_PATH: Find by running which dbt in Terminal (macOS/Linux) or where dbt (Windows) in Powershell
    Local MCP with .env

   Advanced configuration for users who need custom environment variables

   Using the env field (recommended):

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

   Using an .env file (alternative):

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

5. Save the file. Upon a successful restart of Claude Desktop, you'll see an MCP server indicator in the bottom-right corner of the conversation input box.

For debugging, you can find the Claude desktop logs at ~/Library/Logs/Claude for Mac or %APPDATA%\Claude\logs for Windows.

Troubleshooting

• Claude desktop may return errors such as Error: spawn uvx ENOENT or Could not connect to MCP server dbt-mcp. Try replacing the command and environment variables file path with the full path. For uvx, find the full path to uvx by running which uvx on Unix systems and placing this full path in the JSON. For instance: "command": "/the/full/path/to/uvx".

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.