Skip to main content

Integrate Claude with dbt MCP

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

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

You don't need to clone the dbt-mcp repository — install uv and run uvx dbt-mcp (or use the configs later in this page). Only clone the repository if you want to contribute to dbt MCP.

Claude Desktop​

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.

OAuth and advanced JSON configurations use your access URL with a static subdomain.

To configure Claude Desktop to use the dbt MCP server:

  1. Go to the latest dbt MCP release and download the dbt-mcp.mcpb file.
  2. Double-click the downloaded file to open it in Claude Desktop.
  3. Configure the dbt platform Host. You can find this in your dbt platform account by navigating to Account settings and copying the Access URL.
  4. Enable the server in Claude Desktop.
  5. Ask Claude a data-related question and see dbt MCP in action!

Advanced config with Claude Desktop​

Use advanced configuration when you want to define the dbt MCP server yourself in Claude’s configuration file: the same JSON where Claude stores every MCP server, under mcpServers, with fields such as command, args, and env.

See the MCP install pattern for more info on how to configure the dbt MCP server in Claude's configuration file.

To open the configuration file and add or replace the dbt MCP server entry:

  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 and paste the dbt entry under mcpServers in this file:

     Local MCP with OAuthEnterpriseEnterprise +

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

    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": "YOUR-ACCESS-URL"
          }
        }
      }
    }

    Note: Replace YOUR-ACCESS-URL with your Access URL hostname (for example, abc123.us1.dbt.com). Both abc123.us1.dbt.com and https://abc123.us1.dbt.com are accepted. This enables OAuth authentication without requiring local dbt installation.

     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. Put your .env file in your dbt project root (same folder as dbt_project.yml) and use an absolute path with --env-file.

    Using the env field (single-file configuration):

    IDs are integers, not URLs

    DBT_PROD_ENV_ID, DBT_DEV_ENV_ID, and DBT_USER_ID must be numeric IDs (for example, 54321), not full URLs copied from your browser. DBT_HOST accepts both cloud.getdbt.com and https://cloud.getdbt.com.

    Using an .env file (use an absolute path to .env in your dbt project root):

    {
      "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",
            "/absolute/path/to/your-dbt-project/.env",
            "dbt-mcp"
          ]
        }
      }
    }

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.

Claude Code​

If you use OAuth in the JSON patterns mentioned in the next section, you need a static subdomain for your access URL (see the callout under Claude Desktop on this page).

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 information about local and remote server features.

Set up with local dbt MCP server​

  1. Follow Set up local MCP and choose the configuration that matches your use case:
  2. Add the same dbt server definition to .mcp.json at your project root (the repository root for your workspace). Claude Code loads MCP servers from this file.
  3. Use the same mcpServers JSON shape as in Set up local MCP (command, args, and env, or args with --env-file), matching the patterns in next Example config in .mcp.json section.

If you already completed local MCP setup for another client, reuse that dbt entry in .mcp.json — you don't need a second, separate registration step for Claude Code.

Example config in .mcp.json​

Put your dbt server under the top-level mcpServers key. The following expandable options use the same JSON as Set up local MCP and Advanced config with Claude Desktop on this page.

 Local MCP with OAuthEnterpriseEnterprise +

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

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": "YOUR-ACCESS-URL"
      }
    }
  }
}

Note: Replace YOUR-ACCESS-URL with your Access URL hostname (for example, abc123.us1.dbt.com). Both abc123.us1.dbt.com and https://abc123.us1.dbt.com are accepted. This enables OAuth authentication without requiring local dbt installation.

 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. Put your .env file in your dbt project root (same folder as dbt_project.yml) and use an absolute path with --env-file.

Using the env field (single-file configuration):

IDs are integers, not URLs

DBT_PROD_ENV_ID, DBT_DEV_ENV_ID, and DBT_USER_ID must be numeric IDs (for example, 54321), not full URLs copied from your browser. DBT_HOST accepts both cloud.getdbt.com and https://cloud.getdbt.com.

Using an .env file (use an absolute path to .env in your dbt project root):

{
  "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",
        "/absolute/path/to/your-dbt-project/.env",
        "dbt-mcp"
      ]
    }
  }
}
About claude mcp add

The Claude Code CLI can register MCP servers with claude mcp add, which typically writes local-level configuration. This is still on a per-project basis, but the config is written in the users root directory config (~/.claude.json). This is not obvious and hard to keep track of. For dbt MCP, we recommend .mcp.json in your repository so the setup is project-scoped and easier to share and troubleshoot.

Troubleshooting​

 Claude Desktop errors

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".

 Claude Code

If the dbt MCP server doesn't connect, confirm .mcp.json is at the project root and that the dbt block matches Example configuration in .mcp.json and Set up local MCP. Use the same full-path fixes for uvx (and for --env-file paths) as for Claude Desktop.

Was this page helpful?

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

0
Loading