dbt-mcp: a Model Context Protocol server for dbt Core, Fusion and dbt Platform

The gap dbt-mcp fills for agent workflows

An LLM asked to write a dbt model has no idea what your project looks like. It does not know your model names, your column descriptions, your metric definitions or which tests are currently failing. Without that context it produces plausible SQL that references tables that do not exist. The usual workaround is pasting schema dumps into a prompt, which does not scale and goes stale immediately.

dbt-mcp addresses this by exposing dbt's own metadata and execution surfaces as Model Context Protocol tools. An MCP-aware client connects to the server, sees a list of tools, and can call them during a conversation. The intended audience is data engineers and analytics engineers who already have a dbt project and want an agent to reason about it: listing metrics, tracing lineage, pulling a job run error, or running a model locally. The repository ships example integrations for AG2, the Vercel AI SDK, AWS Strands, CrewAI, Google ADK, LangGraph, OpenAI, OpenAI Responses and Pydantic AI, plus a remote MCP example, which tells you the maintainers expect a broad client matrix rather than one blessed assistant.

How the tool groups are split and where each one runs

The server is not one monolithic API. It is a set of tool groups, and which ones appear depends on configuration. The SQL group (`execute_sql`, `text_to_sql`) runs against dbt Platform infrastructure. The Semantic Layer group (`list_metrics`, `query_metrics`, `get_dimensions`, `get_dimension_values`, `get_entities`, `get_metrics_compiled_sql`, `list_saved_queries`) talks to the dbt Semantic Layer. Discovery wraps the Discovery API for lineage, models, sources, macros, exposures, test results and model health. Admin API covers job management: listing projects and jobs, triggering, retrying and cancelling runs, and pulling artifacts with optional jq filtering. Codegen generates YAML and staging models. The dbt CLI group runs `build`, `compile`, `run`, `test`, `show`, `parse`, `list`, `clone` and `docs` against a local project, with two extra tools that read a local manifest.json.

That split matters because the groups have different prerequisites. Semantic Layer and Admin tools need dbt Platform credentials. The CLI and local lineage tools need a project directory on the machine running the server. The `.env.example` file exposes this directly through `DBT_HOST`, `DBT_PROD_ENV_ID`, `DBT_DEV_ENV_ID`, `DBT_USER_ID`, `DBT_TOKEN`, `DBT_PROJECT_DIR` and `DBT_PATH`, plus per-group toggles such as `DBT_MCP_ENABLE_SEMANTIC_LAYER`, `DBT_MCP_ENABLE_ADMIN_API` and `DBT_MCP_ENABLE_DBT_CLI`. You can also invert the logic with `DBT_MCP_ENABLE_TOOLS` and `DISABLE_TOOLS`.

Installing dbt-mcp and getting a first tool call out of it

The package is published as `dbt-mcp` and requires Python 3.12 or 3.13; the pyproject pins `requires-python = ">=3.12,<3.14"` because pyarrow wheels were not available for 3.14 at the time of the comment in that file. A local install with uv looks like this:

Configuration is where most first attempts fail

The Dockerfile sets `MCP_TRANSPORT=stdio` as the default, and the entrypoint is `dbt-mcp`. A container run therefore starts a stdio server unless you override the transport. That is the right default for desktop clients that spawn a subprocess, and the wrong one for anything that expects an HTTP endpoint.

Credentials come from environment variables. Copy `.env.example` and fill in the values for the groups you intend to use. If you only want local CLI tools, `DBT_PROJECT_DIR` and `DBT_PATH` are the ones that matter. If you want Semantic Layer metrics, you need the Platform token and environment IDs instead. The README does not document what happens when a group is enabled but its credentials are missing, so a half-configured server is a real failure mode: the tools may be listed and then fail at call time, or may not be listed at all.

There is also an experimental MCP bundle, `dbt-mcp.mcpb`, published with each release. The README says MCPB-aware clients can import it without additional setup, and points at Anthropic's `mcpb` CLI for installing or inspecting it. Treat that path as experimental, as the README itself labels it.

The dbt CLI tools can change your warehouse

The README carries an explicit warning above the dbt CLI section: using these tools could modify your data models, sources and warehouse objects, and you should proceed only if you trust the client and understand the impact. This is not boilerplate. `run`, `build` and `clone` materialize objects; `clone` copies selected nodes into target schemas. An agent that misreads a request can trigger a real run.

There is no documented dry-run mode for the CLI group in the README, and no documented approval gate. The practical mitigation is scope: leave `DBT_MCP_ENABLE_DBT_CLI` off when the agent only needs to read lineage and metrics, and turn it on for a session where you are watching. The same applies to the Admin API group, where `trigger_job_run`, `retry_job_run` and `cancel_job_run` affect scheduled production jobs.

Deprecated tools and a pinned MCP SDK

The Discovery group has accumulated deprecations. `get_model_details`, `get_source_details`, `get_test_details`, `get_seed_details`, `get_snapshot_details`, `get_semantic_model_details`, `get_macro_details` and `get_exposure_details` are all marked deprecated in favour of `get_node_details`. `get_model_parents` and `get_model_children` are deprecated in favour of `get_lineage`. An agent given the full tool list may pick a deprecated tool because it looks more specific. If you are writing prompts or tool filters, name `get_node_details` and `get_lineage` explicitly.

The `search` tool is labelled Alpha and the README states it is not generally available. Do not build a workflow on it.

On the dependency side, `mcp[cli]` is pinned to an exact version, `1.26.0`, with a comment in pyproject.toml explaining why: `src/dbt_mcp/proxy/tools.py` accesses private MCP SDK internals, specifically `_tool_manager._tools` and `mcp.server.fastmcp.utilities.func_metadata`. The comment instructs maintainers to verify those APIs are unchanged before upgrading. That is an honest disclosure of a fragile coupling, and it means a routine `uv lock --upgrade` can break the proxy layer.

Alternatives and the difference in approach

The closest alternative is not another MCP server but the dbt CLI itself, wrapped by whatever the agent framework provides. LangGraph, CrewAI and the OpenAI Agents SDK all let you define a function tool that shells out to `dbt run` or `dbt ls`. You get exactly the commands you allow, with no server process, no transport negotiation and no MCP SDK pin. What you lose is the Platform-side surface: Semantic Layer metric queries, Discovery lineage, Admin API job control and codegen are not available from the CLI alone, and you would have to write and maintain each wrapper yourself.

A second option is querying the dbt metadata directly. The repository depends on `dbt-artifacts-parser` and `dbt-protos`, and the local lineage tools read `manifest.json`. A team could parse that file in its own tooling and skip the server entirely. That works for read-only lineage and node details, but it gives you nothing for the Semantic Layer or for triggering jobs, and you inherit the artifact schema churn yourself.

Maintenance, licence and upgrade cost

The last push to the default branch was on 2026-09-10, and v2.3.0 was released on 2026-09-08, with v2.2.1 and v2.2.0 before it. The repository is not archived. Releases are frequent enough that the changelog is worth reading before upgrading, particularly given the deprecation list in Discovery.

The licence is Apache-2.0, declared in pyproject.toml as `license = { file = "LICENSE" }` and classified as `License :: OSI Approved :: Apache Software License`. Apache-2.0 permits commercial and internal use and includes a patent grant; it also requires that you preserve notices. If you fork the server and ship it internally, keep the LICENSE file and any NOTICE content intact. That is a description of the licence terms, not legal advice; check with your own counsel for your situation.

The real upgrade cost is the MCP SDK pin. Because the proxy reaches into private internals, you cannot freely bump `mcp` without checking `_tool_manager._tools` and `mcp.server.fastmcp.utilities.func_metadata`. If your client ecosystem moves to a newer MCP SDK, you may be waiting on the maintainers to adjust that code.

Editorial conclusion

Adopt dbt-mcp if your team already runs dbt Platform and wants an agent to read lineage, metrics and job runs, or if you want a local dbt CLI bridge inside an MCP client. Skip it if you have no dbt Platform account and no local dbt project, because most of the tool surface depends on one or the other. Before trusting it, verify which tool groups your credentials actually enable by checking the DBT_MCP_ENABLE_* variables, and confirm whether your client needs stdio or HTTP transport.

Frequently asked questions

Official sources

1. dbt-labs/dbt-mcp on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases