dbt MCP — Use Cases, Install & Live Demo

Why use it

Key features

First-party — official dbt Labs MCP
Works across dbt Core (local) + dbt Cloud/Platform (hosted)
Semantic Layer integration: list_metrics, query_metrics, get_dimensions
Lineage + model health + performance out of the box

Live Demo

What it looks like in practice

dbt.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "dbt",
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "dbt": {
      "command": {
        "path": "uvx",
        "args": [
          "dbt-mcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add dbt -- uvx dbt-mcp

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use dbt

Diagnose why a dbt model is failing and propose a fix

👤 Analytics engineers ⏱ ~15 min intermediate

When to use: A scheduled dbt run failed. You need to know what broke and why, without opening 5 UIs.

Prerequisites

dbt Cloud account + service token — dbt Cloud → Profile → API Tokens
Local dbt project checkout (if using CLI tools) — git clone your dbt repo

Flow

Find the failing run

List my last 10 job runs in dbt Cloud. Show which ones failed and their error summary.✓ Copied

→ Failed run IDs with timestamps
Drill into the failing model

For the failed run, which model failed first? Get its details (SQL, description) and its upstream lineage.✓ Copied

→ Failing model + dependency chain
Propose fix

Run the model locally with dbt compile. Inspect the compiled SQL for the error. Propose the minimum edit to fix.✓ Copied

→ Concrete SQL fix with rationale

Outcome: A validated fix for a broken model in under 15 minutes.

Pitfalls

Cloud run failures can be environmental (connection/credentials), not code — Before editing SQL, check if the same model runs locally via run tool — if yes, it's infra not code

Combine with: sentry · linear

Answer a business question using the dbt Semantic Layer

👤 Analytics engineers enabling self-serve ⏱ ~10 min beginner

When to use: A stakeholder asks 'what was MRR by plan last month?' — you have metrics defined in dbt SL.

Prerequisites

Semantic Layer enabled on your dbt Platform project — dbt Cloud → Account Settings → Semantic Layer

Flow

Find the metric

List available metrics in our SL. I'm looking for MRR or monthly_revenue.✓ Copied

→ Matching metric found
Check dimensions

What dimensions is the MRR metric queryable by? I want to filter/group by plan and month.✓ Copied

→ Valid dimension list
Query and interpret

Query MRR for last month, grouped by plan. Format the result as a table and comment on biggest contributors.✓ Copied

→ Table + brief analysis

Outcome: Stakeholder gets a trustworthy, governed answer in 2 minutes; no one wrote ad-hoc SQL.

Pitfalls

Querying by an unsupported dimension returns empty without clear error — Always call get_dimensions on the metric first; don't assume

Combine with: notion

Check impact before editing a core model

👤 Analytics engineers about to touch a foundational model ⏱ ~20 min intermediate

When to use: You're about to change dim_customers. You need to know every downstream consumer first.

Flow

Get lineage

Get downstream lineage for dim_customers. Include models, exposures, and any metrics.✓ Copied

→ Full downstream graph
Quantify impact

For each downstream model, get its model_performance and model_health — which are critical (used by exposures, run daily)?✓ Copied

→ Priority list of what'll break if you screw up
Plan the change

Write a change plan: what tests to add, which downstream owners to notify (check exposures), and what to monitor after deploy.✓ Copied

→ Rollout plan

Outcome: Changes to shared models ship with awareness, not blast radius surprises.

Pitfalls

Exposures only exist if you maintain them — silent downstream in BI tools isn't tracked — Combine with your BI tool's API (Looker, Tableau) to find real consumers; dbt only knows what it's told

Scaffold staging models from raw sources

👤 Analytics engineers onboarding a new source ⏱ ~30 min intermediate

When to use: New Fivetran/source data lands. You need a stg_* model + yml for each table.

Prerequisites

sources.yml entries for the new data — Define sources first; agent generates staging from there

Flow

Generate source block

Use generate_source for database 'raw', schema 'stripe'. Write the output to models/staging/stripe/_sources.yml.✓ Copied

→ Source yml populated with all tables
Scaffold staging models

For each source table, call generate_staging_model. Write each to models/staging/stripe/stg_stripe__<table>.sql.✓ Copied

→ One .sql per source table
Add docs + tests

For each new staging model, call generate_model_yaml. Add not_null tests on primary keys. Commit.✓ Copied

→ Clean, tested staging layer

Outcome: A full staging layer in minutes; no copy-paste drift.

Pitfalls

Generated models use SELECT * which then pulls PII columns — After generation, explicitly list columns and exclude/hash any sensitive ones before merging

Combine with: git

Combinations

Pair with other MCPs for X10 leverage

dbt + sentry

When a dbt model failure breaks downstream features, correlate with Sentry error spikes

Find failed dbt runs in the last 24h. For each, check Sentry for error spikes in services that depend on those models' tables.✓ Copied

dbt + linear

File Linear bugs for recurring dbt test failures

List dbt tests that have failed more than 3 times in the last week. For each, create a Linear bug in the Analytics team with the test details.✓ Copied

dbt + notion

Auto-document metrics into a Notion glossary

For every metric in our Semantic Layer, create or update a Notion page in the Metrics Glossary database with name, description, and owner.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_metrics / get_dimensions / get_entities / query_metrics	metric name, dimensions, filters	Business-metric questions	SL queries billable per dbt Cloud plan
execute_sql / text_to_sql	sql or natural language	Ad hoc SQL exploration with dbt context	Warehouse credits
get_all_models / get_model_details / get_lineage	model identifiers	Discovery + impact analysis	free
get_model_health / get_model_performance	model id	SRE-style checks on the data platform	free
build / run / test / compile / parse / show / docs / list	dbt CLI args	Local dbt Core usage	warehouse compute for run/test/build
list_jobs / trigger_job_run / get_job_details / cancel_job_run / retry_job_run / list_job_runs	job/run IDs	dbt Cloud operations	1 Admin API call
generate_source / generate_staging_model / generate_model_yaml	source/model refs	Scaffolding new models	free
get_exposures / get_exposure_details	exposure name	Find downstream consumers documented as exposures	free

Cost & Limits

What this costs to run

API quota: dbt Cloud Admin API: depends on plan. Semantic Layer: per plan limits.
Tokens per call: Lineage graphs + model lists can be large — paginate
Monetary: MCP is free; dbt Core is free; dbt Cloud/Platform is paid. Warehouse queries billed by your warehouse.
Tip: Use discovery tools (get_model_details, get_lineage) freely — those are metadata. Be careful with execute_sql / query_metrics which hit the warehouse.

Security

Permissions, secrets, blast radius

Credential storage: dbt Cloud service token in env var; Core uses your profiles.yml

Data egress: dbt Cloud (cloud.getdbt.com) for Cloud tools; your warehouse for SQL tools

Troubleshooting

Common errors and fixes

401 on Admin API calls

Service token expired or missing the required account. Regenerate at dbt Cloud → Account Settings → Service Tokens.

Semantic Layer tools return 'not configured'

SL is a paid feature and must be enabled per project. Check dbt Cloud → Project Settings → Semantic Layer.

CLI tools (run/build) fail with 'No profile'

Set DBT_PROFILES_DIR to a directory containing profiles.yml, or run from the project root with a local profiles.yml.

Verify: dbt debug

get_lineage returns empty

Manifest is stale. Run parse first to regenerate manifest.json.

Alternatives

dbt vs others

Alternative	When to use it instead	Tradeoff
SQLMesh MCP	You use SQLMesh instead of dbt	Different transformation paradigm; not a direct swap
Direct warehouse MCPs (Snowflake, BigQuery)	You only need raw SQL, not dbt metadata	Lose model/lineage/test awareness

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills