dbt MCP Server

This MCP (Model Context Protocol) server provides tools to interact with dbt. Read this blog to learn more. Add comments or questions to GitHub Issues or join us in the community Slack in the #tools-dbt-mcp channel.

Architecture

Related MCP server: @us-all/dbt-mcp

Setup

1. Install uv

2. Copy the .env.example file locally under a file called .env and set it with your specific environment variables (see the Configuration section of the README.md)

Configuration

The MCP server takes the following environment variable configuration:

Tool Groups

Configuration for Discovery, Semantic Layer, and Remote Tools

Configuration for Remote Tools

Configuration for dbt CLI

It is also possible to set any environment variable supported by your dbt executable (see here for the ones supported in dbt Core).

We automatically set DBT_WARN_ERROR_OPTIONS='{"error": ["NoNodesForSelectionCriteria"]}' so that the MCP server knows if no node is selected when running a dbt command. You can overwrite it if needed but we believe that it provides a better experience when calling dbt from the MCP server, making sure that the tool is selecting valid nodes.

Using with MCP Clients

After going through the Setup, you can use dbt-mcp with an MCP client.

Add this configuration to the respective client's config file. Be sure to replace the sections within <>:

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

<path-to-.env-file> is where you saved the .env file from the Setup step

Claude Code

Run the following command to add the MCP server to Claude Code:

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

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

More info on scopes here

Claude Desktop

Follow these instructions to create the claude_desktop_config.json file and connect.

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

Cursor

Note the configuration options here and input your selections with this link:

Cursor MCP docs here for reference

VS Code

1. Open the Settings menu (Command + Comma) and select the correct tab atop the page for your use case

   • Workspace - configures the server in the context of your workspace

   • User - configures the server in the context of your user

   • Note for WSL users: If you're using VS Code with WSL, you'll need to configure WSL-specific settings. Run the Preferences: Open Remote Settings command from the Command Palette (F1) or select the Remote tab in the Settings editor. Local User settings are reused in WSL but can be overridden with WSL-specific settings. Configuring MCP servers in the local User settings will not work properly in a WSL environment.

2. Select Features → Chat

3. Ensure that "Mcp" is Enabled

4. Open the command palette Control/Command + Shift + P, and select either "MCP: Open Workspace Folder MCP Configuration" or "MCP: Open User Configuration" depending on whether you want to install the MCP server for this workspace or for all workspaces for the user

5. Add your server configuration (dbt) to the provided mcp.json file as one of the servers:

{
	"servers": {
		"dbt": {
			"command": "uvx",
      "args": [
        "--env-file",
        "<path-to-.env-file>",
        "dbt-mcp"
      ]
		}
	}
}

<path-to-.env-file> is where you saved the .env file from the Setup step

6. You can start, stop, and configure your MCP servers by:

• Running the MCP: List Servers command from the Command Palette (Control/Command + Shift + P) and selecting the server

• Utlizing the keywords inline within the mcp.json file

VS Code MCP docs here for reference

Troubleshooting

• Some MCP clients may be unable to find uvx from the JSON config. If this happens, try finding the full path to uvx with which uvx on Unix systems and placing this full path in the JSON. For instance: "command": "/the/full/path/to/uvx".

Tools

dbt CLI

• build - Executes models, tests, snapshots, and seeds in dependency order

• compile - Generates executable SQL from models, tests, and analyses without running them

• docs - Generates documentation for the dbt project

• ls (list) - Lists resources in the dbt project, such as models and tests

• parse - Parses and validates the project’s files for syntax correctness

• run - Executes models to materialize them in the database

• test - Runs tests to validate data and model integrity

• show - Runs a query against the data warehouse

Allowing your client to utilize dbt commands through this MCP tooling could modify your data models, sources, and warehouse objects. Proceed only if you trust the client and understand the potential impact.

Semantic Layer

• list_metrics - Retrieves all defined metrics

• get_dimensions - Gets dimensions associated with specified metrics

• get_entities - Gets entities associated with specified metrics

• query_metrics - Queries metrics with optional grouping, ordering, filtering, and limiting

Discovery

• get_mart_models - Gets all mart models

• get_all_models - Gets all models

• get_model_details - Gets details for a specific model

• get_model_parents - Gets parent nodes of a specific model

• get_model_children - Gets children modes of a specific model

Remote

• text_to_sql - Generate SQL from natural language requests

• execute_sql - Execute SQL on dbt Cloud's backend infrastructure with support for Semantic Layer SQL syntax. Note: using a PAT instead of a service token for DBT_TOKEN is required for this tool.

Contributing

Read CONTRIBUTING.md for instructions on how to get involved!