Dbt Docs MCP

What mattijsdp/dbt-docs-mcp MCP server does

The mattijsdp/dbt-docs-mcp MCP server exposes dbt project metadata through the Model Context Protocol. It reads dbt Docs artifacts, including manifest.json and catalog.json, and presents graph and node information as tools that an MCP-compatible client can call.

It is intended for dbt Core projects. The available metadata covers models, sources, tests, node attributes, compiled SQL, dependencies, and column relationships. It does not execute SQL or provide direct database metadata access; those are listed as possible future extensions rather than current capabilities.

How it works

The server uses the dbt manifest and catalog as input data. Agents can search node names, column names, or compiled SQL to locate relevant parts of a project. After finding a node, they can request its attributes or inspect its direct predecessors and successors in the dbt graph.

Column-level lineage uses additional generated files. The repository includes scripts/create_manifest_cl.py, which combines a dbt manifest and catalog to produce a schema mapping and a column-lineage manifest. These outputs support tracing the upstream sources of a model column and the downstream models or columns that depend on it.

Setup and configuration

The mattijsdp/dbt-docs-mcp MCP server requires Python and uv. Clone the repository, enter its directory, and install the project environment with uv sync when preparing column-level lineage. Run the supplied preprocessing script with paths for the manifest, catalog, schema mapping output, and column-lineage output.

An MCP client configuration starts the server with uv run, the listed Python dependencies, and the mcp run command pointing to src/mcp_server.py. Configuration passes paths through MANIFEST_PATH, SCHEMA_MAPPING_PATH, and MANIFEST_CL_PATH. The example is suitable for clients that support an mcp.json configuration, including Claude Desktop and Cursor.

Column-lineage generation depends on project size and may take hours for a large dbt project. The basic metadata and graph features still depend on having the relevant dbt artifact files available.

Tools and capabilities

Available operations include:

• Searching node names with search_dbt_node_names.
• Finding nodes by column name with search_dbt_column_names.
• Searching compiled node SQL with search_dbt_sql_code.
• Retrieving node details with get_dbt_node_attributes.
• Listing direct upstream dependencies with get_dbt_predecessors.
• Listing direct downstream dependents with get_dbt_successors.
• Tracing column ancestors with get_column_ancestors.
• Tracing column descendants with get_column_descendants.

Limitations and notes

The mattijsdp/dbt-docs-mcp MCP server focuses on reading dbt metadata and lineage artifacts. Column-level lineage requires the separate preprocessing step and its generated files, and processing time can be substantial for larger projects.