dbt MCP Server

This MCP (Model Context Protocol) server provides tools to interact with dbt. Read this blog to learn more.

Architecture

Installation

Want to get going quickly?

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/dbt-labs/dbt-mcp/refs/heads/main/install.sh)"

The installer also serves as an updater, simply run it again and it will detect your exisiting dbt-mcp installation and offers to update it.

Configuration

The MCP server takes the following configuration:

Tool Groups

Configuration for Discovery and Semantic Layer

Configuration for Remote Tools

Configuration for dbt CLI

Using with MCP Clients

After going through Installation, you can use your server with an MCP client.

This configuration will be added to the respective client’s config file. Be sure to replace the sections within <>:

If you used the installation script, the mcp server has been installed in your user directory at ~/.dbt-mcp/.

 {
  "mcpServers": {
    "dbt-mcp": {
      "command": "/Users/<YOUR USERNAME>/.dbt-mcp/.venv/bin/mcp",
      "args": [
        "run",
        "/Users/<YOUR USERNAME>/.dbt-mcp/.venv/lib/python3.12/site-packages/dbt_mcp/main.py"
      ],
      "env": {
        // see config above
        // "DBT_HOST": "cloud.getdbt.com"
        // "DBT_TOKEN": "dbtu_...."
      }
    }
  }
}

<path-to-mcp-executable> depends on your OS:

• Linux & Mac: <path-to-this-directory>/.venv/bin/mcp
• PC: <path-to-this-directory>/.venv/Scripts/mcp

Claude Desktop

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

On Mac, you can find the Claude Desktop logs at ~/Library/Logs/Claude.

Cursor

1. Open the Cursor menu and select Settings → Cursor Settings → MCP
2. Click “Add new global MCP server”
3. Add the config from above to the provided mcp.json file
4. Verify your connection is active within the MCP tab

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. Click “Edit in settings.json” under “Mcp > Discovery”

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

{
    "mcp": {
        "inputs": [],
        "servers": {
          "dbt": {
            "command": "<path-to-mcp-executable>",
            "args": ["run", "<path-to-this-directory>/src/dbt_mcp/main.py"]
          }
        }
    }
}

<path-to-mcp-executable> depends on your OS:

• Linux & Mac: <path-to-this-directory>/.venv/bin/mcp
• PC: <path-to-this-directory>/.venv/Scripts/mcp

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

• Running the MCP: List Servers command from the Command Palette (Control + Command + P) and selecting the server
• Utlizing the keywords inline within the settings.json file

VS Code MCP docs here for reference

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 models of a specific model

Contributing

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