dbt MCP Server Cursor IDE Setup 2026: Official dbt Labs Server, CLI vs Platform

How do you connect dbt to Cursor IDE via MCP? Install uvx (part of the uv Python tooling), then add a dbt entry to ~/.cursor/mcp.json that runs uvx dbt-mcp with DBT_PROJECT_DIR pointing at your dbt project folder and DBT_PATH pointing at your dbt executable. Restart Cursor, and it can run dbt build, dbt test, and dbt run, query your Semantic Layer, and pull model lineage from Discovery — all from chat, against your real project.

This is dbt Labs' own server, not a community wrapper — the package lives at dbt-labs/dbt-mcp on GitHub and is documented directly in dbt's own docs. That matters more than it sounds like it should: a first-party server maintained by the vendor tends to track breaking changes in the underlying product (dbt Core, dbt Fusion, dbt Platform) much faster than a community reimplementation, and dbt Labs has been explicit that the CLI-command tools can genuinely modify your models, sources, and warehouse objects — this isn't a read-only convenience layer like a lot of database MCP servers default to.

What the dbt MCP Server Actually Exposes

Four tool categories, and they map to two different deployment modes:

Not all four are available in every setup. This is the part that trips people up coming from a simpler MCP server: dbt-mcp isn't one server with one tool list, it's two servers with overlapping capability depending on how you run it.

Self-Hosted vs Remote: Pick One Before You Configure Anything

Self-hosted runs uvx dbt-mcp as a local subprocess against your actual dbt project. It's the only mode that gets you the CLI tools (dbt run, dbt build, dbt test) and codegen tools, and it works with dbt Core, the dbt Platform CLI, and the dbt Fusion engine. This is what you want for day-to-day model authoring — writing a new model, running it, checking the test result, iterating, all without leaving Cursor.

Remote connects over HTTP to a server dbt Labs hosts on the managed dbt Platform. No local install. It gets you Semantic Layer queries, SQL execution, metadata discovery, and the Admin API — but explicitly not CLI commands, codegen, or anything that touches a local project. It's built for data consumption: querying metrics, exploring lineage, answering "what feeds this table" questions. It requires a dbt Platform account with API access on your plan.

If you're an analytics engineer actively building models, self-hosted is almost certainly the right call. If you're consuming metrics someone else's dbt project already defines and you don't have (or want) a local dbt project checked out, remote is less setup for the same read-side value.

Prerequisites (Self-Hosted)

Step 1: Find Your dbt Executable Path

which dbt

(where dbt on Windows.) Copy the output — you'll need the full path, not just dbt.

Step 2: Configure mcp.json for CLI-Only Use

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/absolute/path/to/your/dbt/project",
        "DBT_PATH": "/absolute/path/to/dbt"
      }
    }
  }
}

DBT_PROJECT_DIR is the folder containing dbt_project.yml. DBT_PATH is the output from Step 1. Both are required for CLI-mode to work — leave either one out and the server starts but the CLI tools fail.

Two optional variables worth knowing about even if you don't set them immediately: DBT_PROFILES_DIR (defaults to ~/.dbt/ — set this only if your profiles.yml lives somewhere nonstandard) and DBT_CLI_TIMEOUT (defaults to 60 seconds — bump this if a dbt build on a large project routinely takes longer and you're seeing timeout errors rather than real failures).

Step 3: Restart and Verify

Restart Cursor completely, then ask in chat:

Run dbt debug on this project through the dbt MCP server and tell me what it reports

If it comes back with a real connection status instead of an error about a missing tool, the CLI path is wired up correctly.

Step 4 (Optional): Add dbt Platform Features

CLI-only setup doesn't get you Semantic Layer or Discovery queries against your dbt Platform account — those need platform credentials layered on top:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "https://your-account.us1.dbt.com",
        "DBT_TOKEN": "your-service-token-or-pat",
        "DBT_PROD_ENV_ID": "your-numeric-env-id",
        "DBT_PROJECT_DIR": "/absolute/path/to/your/dbt/project",
        "DBT_PATH": "/absolute/path/to/dbt"
      }
    }
  }
}

DBT_HOST, DBT_TOKEN, and DBT_PROD_ENV_ID are required for platform features. Two more — DBT_DEV_ENV_ID and DBT_USER_ID — are specifically required if you want the execute_sql tool to work; DBT_ACCOUNT_ID is needed for Admin API calls and PAT-based auth. If you only care about CLI commands against your local project, skip this step entirely — it's additive, not required.

Controlling Which Tools Are Live

dbt-mcp ships every toolset enabled by default, with two exceptions: DISABLE_SQL and DISABLE_DBT_CODEGEN are disabled by default — you have to explicitly opt in if you want raw SQL execution or codegen tools available to the agent. Everything else (DISABLE_DBT_CLI, DISABLE_SEMANTIC_LAYER, DISABLE_DISCOVERY, DISABLE_ADMIN_API, DISABLE_LSP) you set to "true" to turn off.

There's also an allowlist mode — set DBT_MCP_ENABLE_DBT_CLI=true (and the matching DBT_MCP_ENABLE_* variables) to activate only specific toolsets instead of disabling individual ones from the full set. Don't mix the two modes for the same toolset; the docs are explicit that combining disable-style and enable-style variables for the same category produces unpredictable behavior. Pick one approach — allowlist if you want a tight, deliberate tool surface, disable-list if you want everything except a couple of things you've ruled out.

Why the CLI Tools Deserve a Second Thought

This is worth being direct about: dbt build, dbt run, and the rest of the CLI toolset don't simulate anything. When an agent calls them through MCP, they run exactly like you typing the command yourself — against your actual warehouse, modifying actual tables. dbt Labs' own documentation flags this directly: allowing CLI tooling through MCP can modify your models, sources, and warehouse objects. That's not a reason to avoid the self-hosted server, but it is a reason to run it against a dev target or a project with reasonable environment separation, not directly against a production schema, especially while you're still getting a feel for what an agent decides to run unprompted.

Practical Workflows

Iterating on a model without leaving chat

Update the stg_orders model to add a discount_pct column computed from 
list_price and sale_price, then run dbt build on just that model and 
show me the test results

Tracing lineage before a breaking change

Use the Discovery API to show me every downstream model that depends on 
fct_orders before I change its grain

Querying a defined metric instead of writing SQL by hand

Query the revenue_by_region metric from the Semantic Layer for the last 
90 days and show me the top 5 regions

Troubleshooting

uvx dbt-mcp fails immediately, no server output
uv isn't installed or isn't on PATH. Confirm with uvx --version in a terminal before touching Cursor's config — if that fails, the problem is your local uv install, not MCP.

CLI tools error with something like "dbt not found"
DBT_PATH is wrong or stale. Re-run which dbt, and be aware this changes if you're using a virtualenv or version manager where the active dbt install can shift between shells.

Semantic Layer or Discovery tools return an auth error
DBT_HOST, DBT_TOKEN, or DBT_PROD_ENV_ID is missing or incorrect — these are platform-only credentials, separate from anything CLI-mode needs. Double check the token hasn't expired and that DBT_HOST includes your account's actual subdomain, not a placeholder.

A dbt build through the agent times out on a large project
Raise DBT_CLI_TIMEOUT above its 60-second default rather than assuming the run failed — a genuinely large project can take longer than that even outside of MCP.

Enabling one toolset seems to silently break another
Check whether mcp.json mixes DISABLE_* and DBT_MCP_ENABLE_* variables for the same category. The two modes aren't meant to be combined per-toolset.

When Not to Use This

If you don't have a local dbt project — you're purely consuming dashboards or metrics someone else built — the self-hosted CLI setup here is more than you need. Look at the remote MCP server instead, which skips local installation entirely for the read-side use cases (metrics, lineage, metadata). And if your dbt project only ever runs in CI against a shared warehouse, think carefully before pointing DBT_PROJECT_DIR and DBT_PATH at a setup where an agent-triggered dbt build could touch something a teammate is actively relying on.

Frequently Asked Questions

Q: Is dbt-mcp an official dbt Labs product?
A: Yes. Unlike a lot of vendor-integration MCP servers that are community-built, dbt-mcp is maintained directly by dbt Labs and documented in dbt's own docs site, alongside quickstarts for Cursor, Claude, VS Code, and Snowflake Cortex.

Q: Do I need a dbt Platform account to use this with Cursor?
A: Not for the CLI tools — self-hosted CLI-only mode works against dbt Core, the dbt Platform CLI, or dbt Fusion with just DBT_PROJECT_DIR and DBT_PATH. A dbt Platform account is only required if you want Semantic Layer, Discovery, or Admin API features layered on top.

Q: Can the agent actually modify my warehouse through this?
A: Yes, if CLI tools are enabled. dbt run and dbt build execute for real against whatever target your profiles.yml points to — there's no sandbox. dbt Labs' documentation calls this out directly as something to be deliberate about.

Q: What's the difference between self-hosted and remote MCP modes?
A: Self-hosted runs locally via uvx dbt-mcp and is the only mode with CLI commands and codegen tools, but needs a local dbt project. Remote connects over HTTP to a dbt Labs-hosted server, skips local setup, and covers Semantic Layer, SQL, metadata, and Admin API — but has no CLI or local project support.

Q: Why are DISABLE_SQL and DISABLE_DBT_CODEGEN different from the other disable flags?
A: Every other toolset ships enabled by default and you disable what you don't want. Raw SQL execution and codegen are the two exceptions — they're off by default, so you have to explicitly opt in with the matching enable variable if you want them.

Related Guides

Official docs cited