dbt MCP Server

About

The dbt MCP Server is dbt Labs’ own first-party server, and it is unusually large: 61 tools across nine toolsets, covering dbt Core, dbt Fusion and the dbt platform from one process. The Discovery toolset reads your project’s metadata graph — get_all_models, get_lineage, get_node_details, get_model_health and get_model_performance answer “what does this model depend on and did it pass last night” without opening the warehouse. The Semantic Layer toolset (list_metrics, query_metrics, get_dimensions, get_metrics_compiled_sql) is the one that makes governed numbers possible: the agent queries your defined metrics rather than inventing SQL against raw tables. The dbt CLI toolset runs build, run, test, compile, parse, show and list against a local project, and the Admin API toolset triggers, retries, cancels and inspects platform job runs. Codegen (generate_source, generate_staging_model, generate_model_yaml), Fusion column-level lineage, and product-docs search round it out. It ships in two flavours. Self-hosted runs beside your client via `uvx dbt-mcp` and is the only flavour that can execute dbt CLI commands or Codegen; the remote server at /api/ai/v1/mcp/ on your dbt platform host needs no install but is consumption-only. Auth is either DBT_TOKEN or an interactive OAuth login that caches its context in ~/.dbt/mcp.yml — and the fallback between them is silent, which is the single most common way a first run appears to hang. Python 3.12 or 3.13 only; 3.14 is blocked on pyarrow wheels.

Installation

uvx dbt-mcp

Connecting the dbt MCP server

1. 1.Check your Python version before anything else

   pyproject.toml pins requires-python to >=3.12,<3.14. The upper bound is deliberate and is commented in the file: pyarrow has not released 3.14 wheels. On a 3.14 interpreter uv will fail to resolve rather than fail to run, which reads like a network problem and is not one.

   shell

   python3 --version   # must be 3.12.x or 3.13.x

2. 2.Decide remote or self-hosted

   If the agent only needs to explore metadata, read lineage and query Semantic Layer metrics, point your client at the remote server on your own dbt platform host and skip the rest of the install. The remote flavour supports the Semantic Layer, SQL, Discovery, Admin API, Fusion, product-docs and metadata toolsets — but not the dbt CLI toolset and not Codegen. Continue below only if you want those, or you want the server running on your own machine against a local project.

   remote endpoint

   https://<your-account-prefix>.<your-host>/api/ai/v1/mcp/

3. 3.Install uv, not pip

   The published console script is dbt-mcp and the documented way to start it is uvx dbt-mcp, which resolves the package into an isolated environment on each run. A bare pip install dbt-mcp puts the package somewhere, but it does not give your MCP client a command it can find, and a dbt-mcp installed into the same environment as your dbt adapters is exactly the dependency conflict uv exists to avoid. Latest release is 2.1.2 (2026-08-20).

   shell

   curl -LsSf https://astral.sh/uv/install.sh | sh
   uvx dbt-mcp --help

4. 4.Add the server to your MCP client

   DBT_PROJECT_DIR must point at a directory that contains dbt_project.yml, and DBT_PATH must be a dbt executable that actually exists — settings.py validates both, and dbt and dbtf are the two names it will accept from $PATH without a full path. If you are only using platform tools and have no local checkout, leave both out and set DISABLE_DBT_CLI=true so the CLI toolset does not try to load.

   claude_desktop_config.json

   {
     "mcpServers": {
       "dbt": {
         "command": "uvx",
         "args": ["dbt-mcp"],
         "env": {
           "DBT_PROJECT_DIR": "/absolute/path/to/your/dbt/project",
           "DBT_PATH": "dbt",
           "DBT_HOST": "your-host.dbt.com",
           "DBT_TOKEN": "your_service_token",
           "DBT_PROD_ENV_ID": "12345",
           "DBT_DEV_ENV_ID": "67890",
           "DBT_USER_ID": "1122"
         }
       }
     }
   }

5. 5.Set every platform variable the toolsets you want actually require

   This is where most configurations fall over, because the requirements are per-toolset and the error only appears once. Semantic Layer, Discovery, SQL and the Admin API all need DBT_HOST, DBT_TOKEN and either DBT_PROD_ENV_ID or DBT_PROJECT_IDS — setting both of the last two is an error, not a merge. execute_sql additionally needs DBT_DEV_ENV_ID and DBT_USER_ID, and text_to_sql needs DBT_PROD_ENV_ID specifically. DBT_HOST is the bare hostname: strip the scheme, and note that a value beginning with metadata or semantic-layer is rejected outright, because those are the API subdomains people reach for and neither is the right one.

6. 6.Trim the tool list before you hand it to an agent

   Sixty-one tools is more than most clients present well and more than most models choose well between. Two toolsets already ship off — Codegen (DISABLE_DBT_CODEGEN defaults true) and server metadata — and SQL is off unless you explicitly set DISABLE_SQL=false. Prefer the allowlist: set DBT_MCP_ENABLE_TOOLS to just the tools you want, or the DBT_MCP_ENABLE_* flags for whole toolsets. Individual tool settings beat toolset settings, and enables beat disables at the same level.

   env

   DBT_MCP_ENABLE_TOOLS="list_metrics,query_metrics,get_all_models,get_lineage"

7. 7.Smoke test with a metadata call, not a query

   Ask for the model list first. get_all_models exercises the host, the token and the environment id together without depending on the Semantic Layer being configured or the warehouse being reachable, so a failure points at one layer. Only then try a metric query.

   prompt

   List every model in my dbt project and tell me which marts have failing tests.

The nine toolsets

61 tools in total. Everything except the dbt CLI and Codegen toolsets is available on the remote server as well as self-hosted.

What people use it for

Which one should you use?

dbt is the semantic/transformation layer, so the real comparison is not against other dbt servers — there is only one — but against connecting the agent somewhere else in the stack.

Categories

Works With

Frequently Asked Questions

Related Guides