dbt-labs/dbt-mcp

dbt‑MCP Server – A bridge between dbt projects and AI agents

What it is

• An open‑source server that implements the Model Context Protocol (MCP). It exposes a rich set of RPC‑style tools that let an external program (often an LLM‑powered agent) query and act on a dbt project –‑ models, sources, metrics, the semantic layer, job runs, and even generate SQL from natural language.
• The server can run against dbt Core (local), dbt Fusion, or dbt Platform, so the same agent code works whether you’re developing locally or in a managed cloud environment.

Why it matters for AI/ML workflows

• Modern data‑centric AI agents need context: the schema of the warehouse, the definitions of metrics, and the lineage of models. dbt‑MCP gives agents that context in a structured, programmatic way.
• It also lets agents act: run dbt commands, trigger jobs, fetch compiled SQL, or even write new model files via the code‑generation helpers.

Key capabilities (grouped by tool category)

Category	Notable tools	What they let an agent do
SQL	execute_sql, text_to_sql	Run arbitrary SQL on dbt Platform or generate SQL from a natural‑language prompt using the project’s model catalog.
Semantic Layer	list_metrics, query_metrics, get_dimension_values …	Inspect and query the dbt Semantic Layer –‑ retrieve metric definitions, compiled SQL, dimension values, etc.
Discovery	get_all_models, get_lineage, get_node_details, search (alpha)	Browse the whole dbt DAG, fetch metadata for any resource (model, source, exposure, macro, etc.), and perform semantic search across the project.
dbt CLI	run, build, test, compile, list …	Execute ordinary dbt commands remotely, enabling an agent to materialise models, run tests, or generate documentation.
Admin API	trigger_job_run, cancel_job_run, list_jobs, get_job_run_details …	Manage dbt Cloud jobs –‑ start, monitor, retry, or cancel them programmatically.
Codegen	generate_model_yaml, generate_source, generate_staging_model	Auto‑create boiler‑plate dbt files (YAML, source definitions, staging models) from existing warehouse metadata.
dbt LSP	fusion.compile_sql, fusion.get_column_lineage, get_column_lineage	Use the Fusion engine (or local dbt‑LSP) to compile SQL with full Jinja context and trace column‑level lineage.
Product Docs	search_product_docs, get_product_doc_pages	Pull documentation from docs.getdbt.com, useful for agents that need to cite official guidance.
Server metadata	get_mcp_server_version, get_mcp_server_branch	Introspect the running server itself.

Typical workflow for an AI‑powered data assistant

1. Start the MCP server (Docker image or python -m dbt_mcp).
2. The assistant (e.g., Claude, Cursor, a custom LLM chain) connects via the MCP client library (mcpb CLI) and authenticates to your dbt Platform account.
3. The agent queries list_models → builds a mental model of the data warehouse.
4. User asks, “How many active customers did we have last month?”
5. Agent calls text_to_sql (or composes a metric query with query_metrics) to get the exact SQL, then runs it with execute_sql and returns the result.
6. If the user wants a new metric, the agent can call generate_model_yaml and run to materialise it, all without the user writing any dbt code.

Getting started

1. Install – either pull the Docker image (docker pull ghcr.io/dbt-labs/dbt-mcp) or install the Python package from the repo.
2. Obtain a MCP bundle – download dbt-mcp.mcpb from the latest release and install it with Anthropic’s mcpb CLI (see the README link).
3. Run the server – dbt-mcp serve --port 8000 (or the Docker command shown in the docs).
4. Connect – use the mcpb client or any language‑specific SDK to call the tools listed above.
5. Explore examples – the repo’s examples/ folder contains minimal Python scripts that demonstrate a full round‑trip: connect, list models, generate SQL, and execute it.

Who should use it

• Data‑centric AI product teams building chat‑or‑voice assistants that need up‑to‑date dbt metadata.
• Analytics engineers who want to expose their dbt project to internal bots for self‑service reporting.
• Developers of custom agents (e.g., LangChain tools) looking for a turnkey way to give the agent a deep understanding of the data model.

Limitations / cautions

• The server is experimental; some tools are marked deprecated and may be removed in future releases.
• CLI‑type tools (build, run, trigger_job_run) can modify production data; only grant access to trusted agents.
• The search tool is alpha and not generally available yet.

Further reading

• Official docs: https://docs.getdbt.com/docs/dbt-ai/about-mcp
• Intro blog post: https://docs.getdbt.com/blog/introducing-dbt-mcp-server
• MCP bundle CLI: https://github.com/modelcontextprotocol/mcpb

---

All information above is taken directly from the repository’s README; no additional features have been inferred.