dbt MCP Server: Let AI Agents Run and Explain dbt Projects

⏱️ 3 min read 🔌 MCP Server

What it is: The official MCP server from dbt Labs (dbt-labs/dbt-mcp). It gives AI agents structured access to your dbt project: discovering models and their lineage, querying governed metrics through the Semantic Layer, and executing dbt CLI commands like run, test, and compile.

Quick answer: The dbt MCP server is dbt Labs' official bridge between AI agents and dbt. Install it with uvx dbt-mcp, point it at your project via environment variables, and Claude can list models, trace lineage, run dbt commands, and query Semantic Layer metrics. It works with plain dbt Core locally; Semantic Layer and Discovery tools additionally require a dbt Cloud (dbt platform) account.

Why it matters for data work

Without context, an agent asked "what does revenue mean here?" will guess from raw table names. With dbt-mcp it can read the actual model definitions, docs, and metric logic your team already maintains — then answer with the governed definition, or run the exact model that needs a rebuild.

What tools does the dbt MCP server expose?

Three groups, each of which you can enable or disable independently. Discovery tools list models and fetch details like descriptions, columns, and parent/child lineage. Semantic Layer tools list metrics and dimensions and run governed metric queries. CLI tools execute dbt commands — build, run, test, compile, docs — against your local project.

# toggle tool groups via environment variables
DISABLE_DBT_CLI=false
DISABLE_SEMANTIC_LAYER=true   # if you don't use dbt Cloud
DISABLE_DISCOVERY=true

Does it work with dbt Core or only dbt Cloud?

Both, with different feature sets. The CLI tools only need a local dbt Core (or Fusion/Cloud CLI) install plus a project directory — no dbt Cloud account. The Semantic Layer and Discovery tools call dbt Cloud APIs, so they need a host, a service token, and an environment ID. Mixing is fine: many teams run CLI tools locally and Discovery against production metadata.

# dbt Core (local CLI tools)
DBT_PROJECT_DIR=/path/to/your/dbt/project
DBT_PATH=/usr/local/bin/dbt

# dbt Cloud (Semantic Layer + Discovery)
DBT_HOST=cloud.getdbt.com
DBT_TOKEN=<your-service-token>
DBT_PROD_ENV_ID=<environment-id>

How do you configure it in Claude Code?

Register it with claude mcp add or a project-scoped .mcp.json, passing the environment variables the tool groups need:

claude mcp add dbt -e DBT_PROJECT_DIR=/path/to/project -e DBT_PATH=$(which dbt) -- uvx dbt-mcp

# or .mcp.json:
{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/usr/local/bin/dbt"
      }
    }
  }
}

How do you configure it in Claude Desktop or Cursor?

Same JSON shape. For Claude Desktop, add it to claude_desktop_config.json (Settings → Developer → Edit Config) and fully restart the app. For Cursor, put it in .cursor/mcp.json and enable it under Settings → MCP.

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/usr/local/bin/dbt",
        "DBT_TOKEN": "<service-token, if using dbt Cloud>"
      }
    }
  }
}

Should agents be allowed to run dbt build?

Not against production, at least not unsupervised. The CLI tools execute real dbt commands with your local profile — if that profile targets the prod warehouse, an agent-triggered dbt build rebuilds prod tables and burns warehouse credits. Point DBT_PROJECT_DIR at a dev target, keep prod credentials out of the profile the server sees, and set DISABLE_DBT_CLI=true when you only want read-style discovery and metric queries.

Troubleshooting

The usual failure modes, in the order to check them:

1. "dbt command not found" — DBT_PATH must be the absolute path to the dbt binary (which dbt); MCP servers don't inherit your shell PATH. 2. Semantic Layer tools missing — they're disabled automatically without DBT_HOST/DBT_TOKEN/DBT_PROD_ENV_ID. 3. Long-running commands time out — raise DBT_CLI_TIMEOUT. 4. Changes to env vars not picked up — restart the client; Claude Desktop and Cursor read MCP config only at launch. 5. uvx missing — install uv first.

Author & links

Author: dbt Labs (official)

Repo: github.com/dbt-labs/dbt-mcp

License: Apache-2.0

Related skills

Pair it with the dbt docs skill so agents follow your documentation conventions when editing models. For direct warehouse access alongside dbt context, add the Snowflake MCP server or the BigQuery MCP server.

← Back to MCP Servers