dbt-mcp: An MCP Server That Puts Your dbt Project Behind an Agent Tool Call

The gap dbt-mcp fills between an agent and a dbt project

An AI agent asked to explain why a model is stale has no obvious way to read dbt metadata. It can be given a manifest.json as a file, or shell access to the dbt CLI, but neither gives it structured access to metrics, lineage or job history. The dbt MCP server exists to turn those interfaces into named tools that an MCP-aware client can call. The README describes it as providing "various tools to interact with dbt" so that agents get context from dbt Core, dbt Fusion and dbt Platform. That is the whole scope. It is not a scheduler, not a replacement for dbt Cloud jobs, and not a way to run dbt without a project. The audience is data platform teams that already have a dbt project and want an agent to answer questions about it, or to generate boilerplate against it, using the same metadata the dbt UI shows.

Five tool groups, two very different trust levels

The tools are grouped, and the grouping matters more than the individual names. SQL tools (execute_sql, text_to_sql) run SQL on dbt Platform infrastructure. Semantic Layer tools (query_metrics, list_metrics, get_dimensions, get_dimension_values, get_entities, get_metrics_compiled_sql, list_saved_queries) read and query metrics rather than raw tables. Discovery tools read project metadata: get_all_models, get_all_sources, get_lineage, get_node_details, get_model_health, get_model_performance, get_related_models and others. Admin API tools operate on jobs: list_jobs, trigger_job_run, retry_job_run, cancel_job_run, get_job_run_artifacts and similar. Codegen tools generate files: generate_model_yaml, generate_source, generate_staging_model. A final group, dbt LSP, uses the Fusion engine for fusion.compile_sql and fusion.get_column_lineage, with a local get_column_lineage variant. The README's own warning sits above the CLI group, not the read-only groups: using dbt commands "could modify your data models, sources, and warehouse objects." That is the line to draw when deciding what to expose.

The Discovery API surface is migrating, and the deprecated names are still listed

The README lists nine Discovery tools marked deprecated, each with a replacement. get_model_details, get_source_details, get_seed_details, get_snapshot_details, get_test_details, get_macro_details, get_semantic_model_details and get_exposure_details all point at get_node_details. get_model_children and get_model_parents point at get_lineage. If you are writing prompts or tool allowlists against this server, targeting the deprecated names means a future release can drop them. Target get_node_details and get_lineage instead. The same section marks search as Alpha and "not generally available," so it should not appear in a production allowlist. This consolidation is a sensible design: one node lookup with a resource-type argument replaces eight near-identical tools, which reduces the number of tool descriptions an agent has to reason over. The cost is a wider argument surface on a single tool, and the README does not document those arguments here beyond the resource types it names (model, source, exposure, test, seed, snapshot, macro, semantic_model).

Getting it running: the bundle route and the client config route

The README offers two installation paths. The first is the experimental MCP Bundle: "We publish an experimental Model Context Protocol Bundle (dbt-mcp.mcpb) with each release so that MCPB-aware clients can import this server without additional setup." You download dbt-mcp.mcpb from the latest release assets and use Anthropic's mcpb CLI to install or inspect it. The second is a normal MCP server entry in your client's config, which is what the dbt documentation linked from the README covers in detail. This repository's README does not reproduce the config block, the transport options, the environment variables or the authentication steps, so treat docs.getdbt.com/docs/dbt-ai/about-mcp as the setup source and do not guess keys. What the README does establish is that the server is Python, licensed Apache-2.0, and that it is released on a roughly two-week cadence: v2.2.0 on 2026-08-25, v2.2.1 on 2026-09-03, v2.3.0 on 2026-09-08. Pinning a version is straightforward; the bundle filename is versioned per release.

The CLI tools are the part that can change your warehouse

Read-only metadata access and write access are bundled in one server. The dbt CLI group includes build, clone, compile, docs, list, parse, run, show and test, plus two local-manifest readers, get_lineage_dev and get_node_details_dev. The Admin API group includes trigger_job_run and retry_job_run. The README's warning is explicit and worth quoting in full because it is the single most important operational fact here: "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." The practical consequence is that an agent with this server connected can run dbt run against whatever target the environment resolves to. If your MCP client cannot filter tools per session, you are granting that capability whenever you grant any capability. The material does not describe a built-in read-only mode or a dry-run flag, so tool-level filtering on the client side is the control you have.

Where it is the wrong tool

Three cases. First, no dbt Platform account: the SQL, Semantic Layer, Discovery, Admin API and Fusion tools are all described as operating against dbt Platform infrastructure or APIs, so a team running dbt Core against a local warehouse gets the CLI and Codegen groups and little else. Second, no Semantic Layer: query_metrics and list_metrics only mean something if metrics are defined, so a project without a semantic model gains nothing from that group. Third, artifact handling: get_job_run_artifacts returns "a guidance message to retry with a jq_filter" for large artifacts, which means the agent may need two calls and a jq expression to get at a large run_results.json. That is a reasonable guard against flooding a context window, but it is a multi-step interaction the agent has to handle, and the README does not describe what counts as large.

What you would use instead, and how the approach differs

The obvious alternative is the dbt CLI itself, driven by an agent with shell access. There is no MCP layer, no tool schemas, and no per-tool permission surface: the agent composes dbt commands and reads stdout, and you control it with filesystem and process sandboxing rather than a tool allowlist. It works with any agent that can run commands and needs no client-side MCP support. The trade-off is that everything comes back as text, so lineage, model health and metric metadata have to be parsed from command output instead of returned as structured tool results, and Semantic Layer metric queries are not a CLI operation at all. A second alternative is to keep the agent out of dbt and give it the artifacts: parse manifest.json and run_results.json yourself, or expose them through your own internal API. That gives you a narrower, fully auditable surface, but you maintain the parsing and you lose the live job and metric endpoints. dbt-mcp's distinguishing choice is to put read and write operations behind one tool namespace and rely on the client to decide which tools the model may call.

Maintenance cost and the licence position

The release history shows three tagged versions in about two weeks, and the tool list shows nine deprecations already aliased to replacements. Budget for prompt and allowlist maintenance, not just installation: every rename or removal in the Discovery group is a change to whatever your agent was told to call. The experimental MCPB bundle is a second moving part, and the README labels it experimental, so pinning the .mcpb asset to a specific release is safer than tracking latest. The project is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; it also requires that you preserve copyright and licence notices and state significant changes. That is a summary of the licence identifier, not legal advice, and if you redistribute the server inside a product, have counsel read the actual LICENSE file. The README also points to an OpenSSF Best Practices badge and a community Slack channel, #tools-dbt-mcp, for questions, which is where a breaking tool change is likely to surface first.

Editorial conclusion

Adopt dbt-mcp if you run dbt Platform or Fusion and want an agent to read Semantic Layer metrics, Discovery lineage and job runs without writing glue code, and if you can restrict which CLI tools the agent is allowed to call. Do not adopt it if your dbt deployment is Core-only with no Platform account, or if you cannot accept that the build, run, clone and retry_job_run tools can change models and warehouse objects. Before wiring it into an agent, verify three things: which transport and auth mode your client uses, whether your client can exclude individual tools, and which dbt project the local CLI tools resolve to when the server starts.

Official sources

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