dbt MCP Server
Connect AI agents to your governed dbt models, metrics, and jobs over the official remote dbt MCP server.
Updated
What is dbt MCP?
The dbt MCP server is a Model Context Protocol server, built and maintained by dbt Labs, that gives AI agents governed access to your dbt project — its models, metrics, lineage, and platform jobs.
dbt is the analytics-engineering tool teams use to transform, test, and document data models with SQL. The MCP server exposes that governed context to assistants and agents so they can answer questions against trusted, defined metrics instead of writing ad-hoc SQL against raw tables. dbt offers two flavors: a local server (uvx dbt-mcp) for development workflows that need the dbt CLI, and a cloud-hosted remote server for data-consumption use cases.
The remote server is hosted by dbt on the dbt platform at https://cloud.getdbt.com/api/ai/v1/mcp/ (substitute your own dbt host if different), so there's nothing to install. It authenticates with a bearer token — a Personal Access Token or Service Token passed in the Authorization header — or, on supported plans, via OAuth. The specific tools available depend on your dbt plan, since they're backed by dbt's Discovery, Semantic Layer, and Administrative APIs.
Tools the dbt MCP server exposes
| Tool | What it does |
|---|---|
| query_metrics | Run dbt Semantic Layer metric queries with filtering and grouping. |
| list_metrics | Retrieve all metrics defined in the Semantic Layer. |
| get_dimensions | Get the dimensions available for specified metrics. |
| execute_sql | Execute SQL on dbt platform infrastructure with Semantic Layer support. |
| text_to_sql | Generate SQL from natural language using dbt project context. |
| get_all_models | Retrieve the name and description of every model in the project. |
| get_model_details | Get a model's compiled SQL, columns, and schema. |
| get_lineage | Return the full lineage graph of ancestors and descendants for a node. |
| get_model_health | Get run status, test results, and upstream source freshness for a model. |
| list_jobs | List dbt platform jobs, optionally filtered by project or environment. |
| trigger_job_run | Trigger a dbt job run, optionally overriding branch, schema, or settings. |
| get_job_run_error | Get error and warning details for a specific job run. |
Connect the dbt MCP server
Claude Code (remote, token auth)
- 1
Create a dbt access token
In the dbt platform, generate a Personal Access Token (required for execute_sql) or a Service Token. Note your prod/dev environment IDs and user ID.
- 2
Add the MCP server
Run: claude mcp add --transport http dbt https://cloud.getdbt.com/api/ai/v1/mcp/ --header "Authorization: Bearer YOUR_DBT_ACCESS_TOKEN" --header "x-dbt-prod-environment-id: PROD_ENV_ID" --header "x-dbt-user-id: USER_ID"
- 3
Verify the connection
Run /mcp inside Claude Code to confirm the dbt server is connected and its tools are listed. Use numeric IDs only in the headers.
Cursor (remote, token auth)
- 1
Create a dbt access token
Generate a Personal Access Token or Service Token in the dbt platform and copy your numeric prod environment ID and user ID.
- 2
Edit mcp.json
In ~/.cursor/mcp.json add an entry: {"mcpServers":{"dbt":{"url":"https://cloud.getdbt.com/api/ai/v1/mcp/","headers":{"Authorization":"Bearer YOUR_DBT_ACCESS_TOKEN","x-dbt-prod-environment-id":"PROD_ENV_ID","x-dbt-user-id":"USER_ID"}}}}
- 3
Enable in settings
Open Cursor Settings → MCP, confirm the dbt server shows green, and enable its tools for the agent.
Security & permissions
The remote dbt MCP server authenticates with a bearer token in the Authorization header — either a Personal Access Token (PAT) or a Service Token from the dbt platform. A PAT is required for the execute_sql tool; a Service Token works for most other tools. The agent acts with the permissions of that token against your dbt account, so scope it to the minimum needed (read-only metadata vs. SQL execution and job control) and prefer a dedicated Service Token over a personal one where possible. On Enterprise and Enterprise+ plans, OAuth is supported so you don't have to paste long-lived tokens into the client. Treat the token like a database credential: store it as a secret, never commit it, and rotate it if exposed.
Using dbt MCP with Gamut
In a Gamut workflow, the dbt MCP server becomes a tool your agent can call on a schedule or in response to an event — Gamut manages the authenticated connection so the token never lives in your prompt. For example, a nightly run can ask the agent to query a revenue metric from the dbt Semantic Layer, check get_model_health for failed tests or stale sources, and post a summary to Slack; or a data-quality trigger can have the agent inspect get_job_run_error after a failed job and open a ticket. The agent works against your governed, defined metrics rather than raw tables, so results stay consistent with the rest of your stack.
Frequently asked questions
What is the dbt MCP server?
It's an official Model Context Protocol server from dbt Labs that lets AI agents access your dbt project — querying Semantic Layer metrics, exploring model metadata and lineage, running SQL, and managing platform jobs. It comes in a local flavor (uvx dbt-mcp) for development and a cloud-hosted remote flavor for data consumption.
Is the dbt MCP server free?
Yes. The dbt MCP server is free, and the remote server is available on all dbt platform plans including the free tier. The tools you can use depend on your plan, and the text_to_sql tool is the only one that consumes dbt Wizard credits.
Is the dbt MCP server hosted or self-hosted?
Both. dbt hosts the remote server on the dbt platform at https://cloud.getdbt.com/api/ai/v1/mcp/ with no installation required. There's also a local server you run yourself with uvx dbt-mcp when you need dbt CLI commands for development.
How do I connect the dbt MCP server to Claude or Cursor?
Generate a dbt Personal Access Token or Service Token, then point your client at https://cloud.getdbt.com/api/ai/v1/mcp/ as an HTTP MCP server with an Authorization: Bearer header and your environment/user ID headers. In Claude Code use claude mcp add --transport http; in Cursor add the server to mcp.json. Enterprise plans can use OAuth instead of a token.