About dbt Model Context Protocol (MCP) beta
As AI becomes more deeply integrated into data workflows, dbt users need a seamless way to access and integrate dbt's structured metadata and execution context effectively. This page provides an overview of dbt's MCP Server, which exposes this context, supporting use cases such as conversational access to data, agent-driven automation of dbt workflows, and AI-assisted development.
The dbt Model Context Protocol (MCP) server provides a standardized framework that enables users to seamlessly integrate AI applications with dbt-managed data assets regardless of the underlying data platforms. This ensures consistent, governed access to models, metrics, lineage, and freshness across various AI tools.
The MCP server provides access to the dbt CLI, API, the Discovery API, and Semantic Layer. It provides access to private APIs, text-to-SQL, and SQL execution.
For more information on MCP, have a look at Get started with the Model Context Protocol (MCP).
Server Access
There are two ways to install dbt MCP: local and remote.
Available Tools
Supported
The dbt MCP server has access to many parts of the dbt experience related to development, deployment, and discovery. Here are the categories of tools supported based on what form of the MCP Server you connect to as well as detailed information on exact commands or queries available to the LLM.
Tools | Local | Remote |
---|---|---|
dbt CLI | ✅ | ❌ |
Semantic Layer | ✅ | ✅ |
SQL | ✅ | ✅ |
Metadata Discovery | ✅ | ✅ |
Administrative API | ✅ | ❌ |
Disable tools | ✅ | ✅ |
Note that access to the Discovery API and the Semantic Layer API is limited depending on your plan type.
dbt CLI commands
build
: Executes models, tests, snapshots, and seeds in dependency ordercompile
: Generates executable SQL from models, tests, and analyses without running themdocs
: Generates documentation for the dbt projectls
(list): Lists resources in the dbt project, such as models and testsparse
: Parses and validates the project’s files for syntax correctnessrun
: Executes models to materialize them in the databasetest
: Runs tests to validate data and model integrityshow
: Runs a query against the data warehouse
Allowing your client to utilize dbt commands through the MCP tooling could modify your data models, sources, and warehouse objects. Proceed only if you trust the client and understand the potential impact.
Semantic Layer
To learn more about the dbt Semantic layer, click here
list_metrics
: Retrieves all defined metricsget_dimensions
: Gets dimensions associated with specified metricsget_entities
: Gets entities associated with specified metricsquery_metrics
: Query metrics with optional grouping, ordering, filtering, and limitingget_metrics_compiled_sql
: Returns the compiled SQL generated for specified metrics and groupings without executing the query
Metadata Discovery
To learn more about the dbt Discovery API, click here
get_mart_models
: Gets all mart modelsget_all_models
: Gets all modelsget_model_details
: Gets details for a specific modelget_model_parents
: Gets the parent nodes of a specific modelget_model_children
: Gets the children models of a specific modelget_model_health
: Get health signals for a specific model
Administrative API
To learn more about the dbt Administrative API, click here
list_jobs
: List all jobs in a dbt accountget_job_details
: Get detailed information for a specific job including configuration and settingstrigger_job_run
: Trigger a job run with optional parameter overrides like Git branch, schema, or execution parameterslist_jobs_runs
: List runs in an account with optional filtering by job, status, or other criteriaget_job_run_details
: Get comprehensive run information including execution details, steps, artifacts, and debug logscancel_job_run
: Cancel a running job to stop executionretry_job_run
: Retry a failed job run to attempt execution againlist_job_run_artifacts
: List all available artifacts for a job run (manifest.json, catalog.json, logs, etc.)get_job_run_artifact
: Download specific artifact files from job runs for analysis or integration
SQL
⚠️ The SQL tools access the dbt platform endpoints. While MCP usage of the tools doesn't consume dbt Copilot credits, access to the tools is impacted by dbt Copilot credit overages from direct usage of Copilot in dbt.
text_to_sql
: Generate SQL from natural language requestsexecute_sql
: Execute SQL on the dbt platform's backend infrastructure with support for Semantic Layer SQL syntax. Note: using a PAT instead of a service token forDBT_TOKEN
is required for this tool.
MCP integrations
The dbt MCP server integrates with any MCP client that supports token authentication and tool use capabilities.
We have also created integration guides for the following clients:
Troubleshooting
- Some MCP clients may be unable to find
uvx
from the JSON config. This will result in error messages likeCould not connect to MCP server dbt-mcp
. If this happens, try finding the full path touvx
withwhich uvx
on Unix systems and placing this full path in the JSON. For instance:"command": "/the/full/path/to/uvx"
.
Resources
- Refer to our blog on Introducing the dbt MCP Server for more information.