dbt MCP Server

Official MCP server from dbt Labs for interacting with dbt projects: run CLI commands, query the Semantic Layer, and explore models via the Discovery API.

Developer Tools by dbt Labs API Key active

GitHub Docs

Overview

The dbt MCP server is the official Model Context Protocol server maintained by dbt Labs. It exposes dbt Core, dbt Fusion, and dbt Platform capabilities to AI agents so they can introspect projects, run models and tests, query metrics, and execute SQL against the warehouse. It works in two modes: a local uvx-launched server that runs on the developer's machine, and a remote HTTP server hosted on the dbt platform for consumption-only scenarios.

Capabilities are organized into toolsets that can be individually enabled or disabled via environment variables. These include the dbt CLI (build, run, test, compile, etc.), the Discovery API (model, source, exposure, lineage, and health introspection), the Semantic Layer (metric, dimension, and entity queries), the Admin API (job triggers and run monitoring), SQL execution and text-to-SQL, dbt Codegen helpers, dbt LSP/Fusion column-level lineage, and documentation search against docs.getdbt.com.

Because it is maintained by dbt Labs, the server is the canonical way to wire dbt into Claude, Cursor, VS Code, or custom agents. It is Apache-2.0 licensed and distributed via the dbt-mcp package (and an experimental MCPB bundle attached to GitHub releases).

Tools

Tool	Description
`execute_sql`	Execute SQL against the dbt Platform with Semantic Layer integration.
`text_to_sql`	Convert a natural language prompt to SQL using project context.
`list_metrics`	List metrics defined in the Semantic Layer.
`query_metrics`	Query Semantic Layer metrics with grouping and filters.
`get_dimensions`	Retrieve dimensions associated with metrics.
`get_entities`	Retrieve entities associated with metrics.
`get_metrics_compiled_sql`	Compile Semantic Layer metric SQL without executing it.
`list_saved_queries`	List pre-built saved queries from the Semantic Layer.
`get_all_models`	List all models in the dbt project via the Discovery API.
`get_model_details`	Fetch metadata for a specific model.
`get_model_performance`	Retrieve execution performance data for a model.
`get_model_health`	Get test and freshness health for a model.
`get_model_parents`	List upstream parents of a model.
`get_model_children`	List downstream children of a model.
`get_lineage`	Retrieve lineage graph for a node.
`get_all_sources`	List all sources in the project.
`get_source_details`	Retrieve metadata for a specific source.
`get_exposures`	List exposures defined in the project.
`get_exposure_details`	Retrieve metadata for a specific exposure.
`build`	Run `dbt build` against the local project.
`run`	Run `dbt run`.
`test`	Run `dbt test`.
`compile`	Run `dbt compile`.
`parse`	Run `dbt parse` to validate project syntax.
`list`	Run `dbt list` to enumerate resources.
`show`	Run `dbt show` to preview model output.
`docs`	Generate or serve dbt docs.
`clone`	Run `dbt clone`.
`generate_model_yaml`	Generate model YAML with column inheritance (dbt Codegen).
`generate_source`	Introspect schema and generate a source definition.
`generate_staging_model`	Generate boilerplate staging SQL from a source.
`search_product_docs`	Search docs.getdbt.com for relevant pages.
`get_product_doc_pages`	Fetch full Markdown content of dbt doc pages.

Setup Guide

Prerequisites

Python and the uvx runner installed (pip install uv or brew install uv)
For CLI tools: a local dbt project and a working dbt executable
For Platform tools: a dbt Platform account with a service token or PAT, plus your Access URL and environment IDs

Install

No clone needed. uvx will fetch and run the package:

uvx dbt-mcp

Claude Desktop / Cursor configuration

Minimal config for dbt Platform features only:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "abc123.us1.dbt.com",
        "DBT_TOKEN": "dbtu_xxx",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_DEV_ENV_ID": "67890",
        "DBT_USER_ID": "111",
        "DBT_ACCOUNT_ID": "222"
      }
    }
  }
}

Combined local CLI plus Platform setup:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "abc123.us1.dbt.com",
        "DBT_TOKEN": "dbtu_xxx",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_PROJECT_DIR": "/path/to/your/dbt_project",
        "DBT_PATH": "/usr/local/bin/dbt"
      }
    }
  }
}

If you prefer keeping secrets in a file, point uvx at an env file:

{
  "mcpServers": {
    "dbt-mcp": {
      "command": "uvx",
      "args": ["--env-file", "/Users/me/.dbt/mcp.env", "dbt-mcp"]
    }
  }
}

Key environment variables

DBT_HOST, DBT_TOKEN, DBT_PROD_ENV_ID: required for Platform features
DBT_DEV_ENV_ID, DBT_USER_ID: required for execute_sql
DBT_ACCOUNT_ID: required for Admin API and PAT authentication
DBT_PROJECT_DIR, DBT_PATH: required for local CLI tools (DBT_PROFILES_DIR optional, defaults to ~/.dbt/)
DBT_CLI_TIMEOUT: CLI command timeout in seconds (default 60)
DISABLE_* or DBT_MCP_ENABLE_*: toggle toolsets (DBT_CLI, SEMANTIC_LAYER, DISCOVERY, ADMIN_API, SQL, DBT_CODEGEN, LSP, MCP_SERVER_METADATA)
DBT_MCP_LOG_LEVEL: log verbosity (default INFO)

A remote HTTP variant hosted on dbt Platform is also available for clients that prefer not to run a local process. See the docs at docs.getdbt.com/docs/dbt-ai/about-mcp.

If you hit spawn uvx ENOENT, replace "uvx" with the absolute path returned by which uvx.

Use Cases

Let an agent explore an unfamiliar dbt project: list models, inspect lineage, and pull column-level metadata via the Discovery API before suggesting changes.
Ask natural language business questions and have the agent route them through the Semantic Layer to return governed metric values rather than raw SQL guesses.
Automate the scaffolding loop: generate sources, staging models, and YAML for new warehouse tables with dbt Codegen, then dbt build and dbt test from the same chat.
Triage failing runs: trigger or cancel dbt Platform jobs via the Admin API, fetch run artifacts, and ask the agent to summarize errors.
Power a "data assistant" inside Cursor or Claude that can answer "what models depend on stg_orders?" or "show me the freshness health of fct_revenue".

Example Prompts

"List all metrics in our Semantic Layer and query monthly_revenue grouped by region for the last 6 months."
"Run dbt build --select +fct_orders and summarize any test failures."
"Show me the upstream lineage for dim_customers and flag any sources with stale freshness."
"Generate a staging model and YAML for the raw.stripe.charges table."
"Trigger production job 4567 in dbt Platform and tell me when it finishes."

Pros

Officially built and maintained by dbt Labs, so it tracks dbt Core, Fusion, and Platform releases.
Broad coverage: CLI, Discovery API, Semantic Layer, Admin API, Codegen, and docs search in one server.
Granular toolset toggles via DISABLE_* / DBT_MCP_ENABLE_* env vars to limit blast radius.
Distributed via uvx (and an experimental MCPB bundle), so there is no repo to clone.

Limitations

Full feature set requires a paid dbt Platform account with a service token; without it you only get local CLI tools.
Multiple required env vars (DBT_HOST, DBT_TOKEN, DBT_PROD_ENV_ID, DBT_USER_ID, etc.) make first-time setup fiddly.
execute_sql runs real warehouse queries through the agent, which requires careful permissioning and review.

Alternatives

Snowflake MCP server for direct warehouse querying without the dbt layer.
MotherDuck / DuckDB MCP for local analytical SQL workflows.
Generic database MCP servers (Postgres, BigQuery) when you only need SQL access and not dbt metadata.