dbt MCP: give Claude your metric definitions, not just your tables

Every other warehouse MCP server on this site hands Claude tables and lets it work out what "revenue" means. dbt's can hand it the answer to that question first.

The dbt MCP server is official, from dbt Labs, and comes in two forms (dbt docs, checked 22 October 2026):

The tools that matter for analysis:

• Semantic Layer: list_metrics, get_dimensions, get_entities, query_metrics, get_metrics_compiled_sql. Claude asks for a metric by name, and dbt compiles the SQL from your definition.
• Discovery: get_lineage, get_model_health, get_node_details, get_mart_models and more. Claude can see where a number comes from and whether its model ran cleanly.
• SQL: text_to_sql and execute_sql.
• Admin API: list_jobs, get_job_run_error, plus trigger_job_run, retry_job_run and cancel_job_run, which change job state.
• dbt CLI (local only): build, run, test, show, compile and others.

dbt states that the server "doesn't store or retain any production data or job run results"; it reads from the dbt platform when a tool is called.

Remote, in claude.ai (most people)

1. Find your MCP URL in dbt platform: Account settings > Access URLs > MCP Endpoint URL. It looks like https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/.
2. Add it to Claude. On Pro or Max, Customize > Connectors > + > Add custom connector, then paste the URL. On Team or Enterprise, an Owner adds it under Organization settings > Connectors and members connect individually (Anthropic's custom connector help article).
3. Sign in with OAuth. It's in beta and available on Starter, Enterprise and Enterprise+ accounts. With OAuth, you only need the URL.
4. Test with "List the metrics you can see and their descriptions."

Token-based connections are the alternative, but read the fine print in dbt's remote set-up guide: they need the Developer permission set, which on a service token is Enterprise and Enterprise+ only, and access is "all-or-nothing: a token that passes the permission check gets every tool". Use the x-dbt-disable-tools or x-dbt-disable-toolsets headers to trim that down. execute_sql needs a personal access token; service tokens don't work for it.

Local, in Claude Desktop (analytics engineers)

Install uv, then add this to claude_desktop_config.json (from dbt's local set-up guide):

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

The last line is ours, not dbt's. Read the next section before removing it.

The local server's defaults are worth knowing by heart (dbt's environment variables reference):

dbt's own repository warns that allowing dbt commands "could modify your data models, sources, and warehouse objects", and advises enabling the CLI tools only if you trust the client and understand the impact. That's a fair warning about an agent that can run dbt run --full-refresh on your behalf.

What we'd do:

• Analysts and business users: remote server only. It "cannot run dbt CLI commands" at all. Keep execute_sql off unless you need it.
• Use allowlist mode locally. Setting any DBT_MCP_ENABLE_* variable switches the server to enable mode, so only toolsets you name are active: for example DBT_MCP_ENABLE_SEMANTIC_LAYER=true and DBT_MCP_ENABLE_DISCOVERY=true. dbt warns that an empty DBT_MCP_ENABLE_*= line silently disables everything else, so write the values out.
• Point the local CLI at a dev target, never prod. That's a dbt profile setting, not an MCP one, and it matters more than either.
• Disable trigger_job_run, retry_job_run and cancel_job_run with DISABLE_TOOLS (local) or x-dbt-disable-tools (remote) for anyone who doesn't run jobs.

In Claude, approve CLI and job tools one call at a time. Anthropic warns that in Research mode, connector tools can run "automatically without further approval".

The point of dbt's server is that Claude can ask for revenue rather than write it. These prompts make it do that (examples illustrative).

Find the definitions:

Using the dbt connector, list the metrics in the Semantic Layer with their
descriptions. For monthly_recurring_revenue and churn_rate, show the dimensions
they can be grouped by and the compiled SQL behind each.

Answer from a metric, not from scratch:

What was churn_rate by plan for each month of Q3 2026? Use query_metrics only. If
there's no governed metric that matches the question, tell me instead of writing
SQL. Report the metric name and the filters you applied.

Trace a number upstream:

The September MRR on the finance dashboard looks low. Use get_lineage on the model
behind monthly_recurring_revenue and get_model_health on each upstream model. Did
any of them fail, warn or run late this week?

Debug a failed job:

List today's failed job runs. For each, fetch the run error and tell me which model
failed and why. Don't retry or trigger anything.

The second prompt's "tell me instead of writing SQL" is the important line. Without it, Claude will happily fall back to text_to_sql and invent a definition when the governed one doesn't fit.

dbt's remote server reads metadata and the Semantic Layer; the local one can also run commands. The documented incidents show why that difference matters.

• 1 April 2025: tool poisoning. Invariant Labs showed hidden instructions in a tool description making a model read files and pass them on. Their mitigations include pinning server versions, which for uvx dbt-mcp means pinning a release rather than pulling the latest each launch.
• 26 May 2025: GitHub MCP. A malicious public issue led an agent with "Always Allow" on to leak private-repository data into a public pull request (Invariant Labs). dbt projects live in Git; an analytics engineer with both servers connected is in the same position.
• 8 July 2025: Supabase MCP. Hidden instructions in a support ticket led an agent with an over-privileged database key to read a tokens table and post it out (General Analysis). Their advice: least-privilege roles and keeping secrets out of reach.

For dbt specifically: a service token that "gets every tool" is the over-privileged key in that story. Use OAuth or a PAT tied to a person, trim tools with the disable headers, and don't run a write-capable dbt server in the same Claude session as a connector that reads untrusted text.

Ask a model for churn against raw tables and it picks a definition. Logo or revenue churn gives 33% or 50% on the same three customers (ChartMogul). A rolling or calendar month gives different MAU (Google Analytics uses rolling 30 days). Each choice is valid SQL and a confident number.

The benchmarks say real schemas are hard. The best agent in the original Spider 2.0 paper solved 21.3% of enterprise text-to-SQL tasks against 91.2% on Spider 1.0 (Lei et al., November 2024). Spider 2.0 now has a dbt track, and its top agent scores 65.6 (leaderboard, read 22 October 2026): building and fixing real dbt projects remains well short of solved. An expert audit also found annotation errors in 62.8% of Spider 2.0-Snow items, often from ambiguous questions (Jin et al., January 2026). More in text-to-SQL.

dbt's Semantic Layer is the most direct fix we know of. When Claude calls query_metrics, the definition was written once, usually reviewed in a pull request, and is shared with every dashboard. The model's job shrinks from "decide what churn means" to "pick the right metric and filters", which it does far more reliably.

Fair counterpoints. It only covers metrics you've defined, and most teams have defined fewer than they think. And text_to_sql is still in the toolset, so Claude can drift off the governed path unless you tell it not to. See semantic layers for AI.

1. Which tool answered? query_metrics means a governed definition. text_to_sql or execute_sql means Claude wrote it; read the SQL.
2. Which metric and filters? Check the metric name against your dbt project, and the filters against the question.
3. Is the model healthy? Ask for get_model_health on the model behind the number. A failed or stale upstream run makes a correct query wrong.
4. Did anything change? If CLI or Admin tools were enabled, check for runs or job triggers you didn't ask for.
5. Ask Claude: "Which figures came from a tool result, and which did you calculate or assume?"

For answers going into a decision, Count makes the audit explicit. Connect Count's MCP server to Claude alongside dbt and ask it to check the answer. It replies with a link to a canvas where every claim is labelled (Citation, Assumption, Model knowledge or Hallucination) and has a reasoning chain showing the tool calls and calculations underneath. A figure that came from a governed metric traces to that call; one Claude derived on its own shows as an Assumption. The canvas also connects to your warehouse, so you can re-run the query there.

What is the dbt MCP server?

What's the difference between the remote and local dbt MCP server?

Can the dbt MCP server change my warehouse?

Does the dbt MCP server work with Claude?