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, plus basic coding features.
• Claude Code: A terminal/IDE tool for development.

Both interfaces can connect to either:

• Local dbt MCP server (runs on your machine, supports CLI commands like dbt run)
• Remote dbt MCP server (HTTP, no install, consumption-focused).

Prerequisites

• You use Claude for AI or agentic work
• For OAuth (local or remote), use your access URL with a static subdomain.

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.

Claude Desktop

Claude Desktop reads MCP servers from claude_desktop_config.json. Open it from Settings → Developer → Edit Config.

Set up with local dbt MCP server

For a fast first install, you can download the prebuilt .mcpb file; for more control, edit the JSON directly.

tip

You don't need to clone the dbt-mcp repository — for local setups, 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.

Quick install with the .mcpb file

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 like command, args, and env. See the MCP install pattern for the underlying convention.

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

1. From Claude, go to Settings…

2. In the Settings window, select the Developer tab.

3. Click Edit Config and open the file in a text editor.

4. Add your server configuration under mcpServers. Choose the option that fits your use case:

    Local MCP with OAuthEnterpriseEnterprise +

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

   Before you begin, make sure your account admin enables AI features on your dbt platform account to use OAuth. Refer to Enable dbt Copilot for more info.

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

   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": "YOUR-ACCESS-URL",
           "DBT_PROJECT_DIR": "/path/to/project",
           "DBT_PATH": "/path/to/dbt/executable"
         }
       }
     }
   }

   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.

    Local MCP (CLI only)

   Local configuration for users who only want to use dbt 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"
         ]
       }
     }
   }

5. Save the file and restart Claude Desktop. You'll see an MCP server indicator in the bottom-right corner of the conversation input box.

For more configuration options (env vars, service tokens, tool-access controls), refer to Set up local MCP.

Set up with remote dbt MCP server

The remote dbt MCP server runs in dbt platform — no uvx or local install needed. Claude Desktop connects to it over HTTP.

info

Remote MCP OAuth is available for Enterprise and Enterprise+ accounts. Contact your account manager to join the private beta.

1. From Claude Desktop, go to Settings → Developer → Edit Config to open claude_desktop_config.json.

2. Get your MCP URL:

   You can copy your full MCP URL from Account settings → Access URLs → MCP Endpoint URL in dbt platform, and paste it directly into your AI tool.

    Build your own MCP URL

   We recommend using the MCP URL from Account settings → Access URLs → MCP Endpoint URL in dbt platform. However, if you want to build your own MCP URL, use your Access URL from Account settings in dbt platform. The remote MCP endpoint is https://YOUR_DBT_HOST_URL/api/ai/v1/mcp. Replace YOUR_DBT_HOST_URL with your hostname only (no https://).

   For default hosts, multi-cell accounts, and regions, see Access, Regions, & IP addresses.

3. Add a dbt entry under mcpServers, using the tab that matches your auth method:

   OAuth (remote)

   OAuth is in private beta for Enterprise and Enterprise+ accounts.

   Before you connect

   • Your MCP client must support OAuth for HTTP-based MCP servers. If it doesn't, use token-based authentication instead.
   • On first connect, your client opens a browser for sign-in. dbt then shows a consent screen with the scopes (the specific permissions the client is allowed to use) it's requesting — see Scopes and consent for what each scope means.
   • Most modern MCP clients self-register on first connect via dynamic registration (RFC 7591). Clients that don't support it need an admin to register them in Account settings → Integrations → App integrations. See Manual registration.

   For the full flow, sessions, and limitations, refer to OAuth (remote MCP).

   Add the following to claude_desktop_config.json. Claude Desktop opens a browser for sign-in and consent the first time the server connects.

   {
     "mcpServers": {
       "dbt": {
         "type": "http",
         "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
       }
     }
   }

   Replace YOUR_DBT_HOST_URL with your hostname (for example, abc123.us1.dbt.com). You can find the URL in dbt platform under Account settings → Access URLs → MCP Endpoint URL.

   Token-based

   Use token-based auth when your client doesn't yet support OAuth for HTTP MCP servers, or when you need a shared/CI setup.

   {
     "mcpServers": {
       "dbt": {
         "type": "http",
         "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/",
         "headers": {
           "Authorization": "Token YOUR_DBT_ACCESS_TOKEN",
           "x-dbt-prod-environment-id": "DBT_PROD_ENV_ID",
           "x-dbt-user-id": "DBT_USER_ID",
           "x-dbt-dev-environment-id": "DBT_DEV_ENV_ID"
         }
       }
     }
   }

   For token-based remote MCP, set these headers in your client's MCP config:

   • Authorization (required) — Token YOUR_DBT_ACCESS_TOKEN or Bearer YOUR_DBT_ACCESS_TOKEN. Use a personal access token (PAT) or a service token with at least Semantic Layer, Metadata, and Developer permissions.
   • x-dbt-prod-environment-id (required) — your dbt platform production environment ID. Find it on the Orchestration page.
   • x-dbt-dev-environment-id — required for execute_sql and Fusion tools.
   • x-dbt-user-id — required for execute_sql. Refer to Find your user ID.

   Use numeric IDs, not full URLs

   Headers like x-dbt-prod-environment-id, x-dbt-dev-environment-id, and x-dbt-user-id expect numeric IDs (for example, 54321), not full URLs copied from your browser. The host in the url field, on the other hand, must include https://.

   execute_sql does not work with service tokens — you must use a PAT. For the complete list of headers (including tool-disable options) and the full table, refer to Set up remote MCP.

4. Save the file and restart Claude Desktop. Ask Claude a data question to confirm the server is connected.

Claude Code

Claude Code reads MCP servers from .mcp.json at the root of your project (the repository root for your workspace). If you already configured the dbt MCP server for another client, you can reuse the same JSON shape here — you don't need a second, separate registration.

Set up with local dbt MCP server

tip

You don't need to clone the dbt-mcp repository — for local setups, 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.

1. Follow Set up local MCP to choose your auth pattern:

   • OAuth with the dbt platform
   • CLI only
   • Environment variables (including an .env file with --env-file)

2. Create .mcp.json at the project root and add a dbt entry under the top-level mcpServers key. Pick the option that fits your use case:

    Local MCP with OAuthEnterpriseEnterprise +

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

   Before you begin, make sure your account admin enables AI features on your dbt platform account to use OAuth. Refer to Enable dbt Copilot for more info.

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

   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": "YOUR-ACCESS-URL",
           "DBT_PROJECT_DIR": "/path/to/project",
           "DBT_PATH": "/path/to/dbt/executable"
         }
       }
     }
   }

   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.

    Local MCP (CLI only)

   Local configuration for users who only want to use dbt 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, but it typically writes to the user-level config (~/.claude.json) rather than the project's .mcp.json. For dbt MCP, we recommend committing .mcp.json to your repository so the setup is project-scoped and easier to share.

Set up with remote dbt MCP server

Claude Code can connect to the remote dbt MCP server over HTTP — same JSON shape as Claude Desktop, lives in .mcp.json instead of claude_desktop_config.json.

info

Remote MCP OAuth is available for Enterprise and Enterprise+ accounts. Contact your account manager to join the private beta.

1. Open .mcp.json at the root of your project (create it if it doesn't exist).

2. Get your MCP URL:

   You can copy your full MCP URL from Account settings → Access URLs → MCP Endpoint URL in dbt platform, and paste it directly into your AI tool.

    Build your own MCP URL

   We recommend using the MCP URL from Account settings → Access URLs → MCP Endpoint URL in dbt platform. However, if you want to build your own MCP URL, use your Access URL from Account settings in dbt platform. The remote MCP endpoint is https://YOUR_DBT_HOST_URL/api/ai/v1/mcp. Replace YOUR_DBT_HOST_URL with your hostname only (no https://).

   For default hosts, multi-cell accounts, and regions, see Access, Regions, & IP addresses.

3. Add the dbt entry to .mcp.json using the tab that matches your auth method:

   OAuth (remote)

   OAuth is in private beta for Enterprise and Enterprise+ accounts.

   Before you connect

   • Your MCP client must support OAuth for HTTP-based MCP servers. If it doesn't, use token-based authentication instead.
   • On first connect, your client opens a browser for sign-in. dbt then shows a consent screen with the scopes (the specific permissions the client is allowed to use) it's requesting — see Scopes and consent for what each scope means.
   • Most modern MCP clients self-register on first connect via dynamic registration (RFC 7591). Clients that don't support it need an admin to register them in Account settings → Integrations → App integrations. See Manual registration.

   For the full flow, sessions, and limitations, refer to OAuth (remote MCP).

   Add the following to .mcp.json at your project root. On first connect, Claude Code opens a browser for sign-in and consent.

   {
     "mcpServers": {
       "dbt": {
         "type": "http",
         "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
       }
     }
   }

   Replace YOUR_DBT_HOST_URL with your hostname (for example, abc123.us1.dbt.com). You can find the URL in dbt platform under Account settings → Access URLs → MCP Endpoint URL.

   You can also register the same server from the CLI:

   claude mcp add --transport http dbt https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/

   Token-based

   {
     "mcpServers": {
       "dbt": {
         "type": "http",
         "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/",
         "headers": {
           "Authorization": "Token YOUR_DBT_ACCESS_TOKEN",
           "x-dbt-prod-environment-id": "DBT_PROD_ENV_ID",
           "x-dbt-user-id": "DBT_USER_ID",
           "x-dbt-dev-environment-id": "DBT_DEV_ENV_ID"
         }
       }
     }
   }

   For token-based remote MCP, set these headers in your client's MCP config:

   • Authorization (required) — Token YOUR_DBT_ACCESS_TOKEN or Bearer YOUR_DBT_ACCESS_TOKEN. Use a personal access token (PAT) or a service token with at least Semantic Layer, Metadata, and Developer permissions.
   • x-dbt-prod-environment-id (required) — your dbt platform production environment ID. Find it on the Orchestration page.
   • x-dbt-dev-environment-id — required for execute_sql and Fusion tools.
   • x-dbt-user-id — required for execute_sql. Refer to Find your user ID.

   Use numeric IDs, not full URLs

   Headers like x-dbt-prod-environment-id, x-dbt-dev-environment-id, and x-dbt-user-id expect numeric IDs (for example, 54321), not full URLs copied from your browser. The host in the url field, on the other hand, must include https://.

   execute_sql does not work with service tokens — you must use a PAT. For the complete list of headers (including tool-disable options) and the full table, refer to Set up remote MCP.

4. Save the file. Claude Code picks up .mcp.json on startup — ask it a data question to confirm the connection.

Troubleshooting

 Claude Desktop errors

Claude Desktop may return errors such as Error: spawn uvx ENOENT or Could not connect to MCP server dbt-mcp. For local setups, replace the command with the full path to uvx: run which uvx on Unix systems or where uvx on Windows and paste the full path into your JSON (for example, "command": "/the/full/path/to/uvx"). For remote setups, double-check that url ends in /api/ai/v1/mcp/ and that your Authorization header is Token YOUR_DBT_ACCESS_TOKEN or Bearer YOUR_DBT_ACCESS_TOKEN.

Logs are at ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\logs (Windows).

 Claude Code

If the dbt MCP server doesn't connect, confirm .mcp.json is at the project root and that the dbt block matches one of the examples on this page. For local setups, apply the same full-path fix for uvx (and for --env-file paths). For remote setups, verify the URL and headers, and try the equivalent claude mcp add --transport http command to compare.

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.