DBT Docs

You can run and use the dbt-docs MCP server to interact with your dbt project metadata, explore the dbt graph, and inspect node and column lineage. This MCP server exposes tools to search, inspect, and trace relationships across models, sources, tests, and their columns, making it easier to understand how data flows through your dbt project.

How to use

Connect your MCP client to the dbt-docs MCP server to access dbt graph information, node attributes, and lineage queries. You can perform searches by node name or column name, inspect detailed node attributes, and traverse upstream and downstream relationships. For column-level insights, trace all upstream sources for a specific column or all downstream descendants.

How to install

Prerequisites: you need Python installed on your machine and the MCP runtime (uv) available to run stdio MCP servers.

Step 1: Clone the project repository and open the directory.

Step 2: Install the required dependencies for the server and any Python packages your environment needs.

Step 3: Optional — parse your dbt manifest for column-level lineage. Follow these steps exactly to generate the schema and manifest column lineage files.

Step 4: Run the MCP server using an MCP client configuration. Use the following example as the starting point for your mcp.json configuration.

{
  "mcpServers": {
    "DBT Docs MCP": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "networkx,mcp[cli],rapidfuzz,dbt-core,python-decouple,sqlglot,tqdm",
        "mcp",
        "run",
        "/Users/mattijs/repos/dbt-docs-mcp/src/mcp_server.py"
      ],
      "env": {
        "MANIFEST_PATH": "/Users/mattijs/repos/dbt-docs-mcp/inputs/manifest.json",
        "SCHEMA_MAPPING_PATH": "/Users/mattijs/repos/dbt-docs-mcp/outputs/schema_mapping.json",
        "MANIFEST_CL_PATH": "/Users/mattijs/repos/dbt-docs-mcp/outputs/manifest_column_lineage.json"
      }
    }
  }
}

Additional configuration and notes

The server is designed to work with dbt manifest and catalog artifacts. If you run into issues during startup, verify that the paths to the manifest, catalog, and column lineage outputs exist and are accessible by the process. Ensure your Python environment has the necessary dependencies listed in the runtime notes for MCP usage.

Tools and capabilities

The dbt-docs MCP server provides the following tools to explore and analyze your dbt project:

• Search dbt nodes by name using search_dbt_node_names to locate models, sources, tests, and other nodes.
• Search by column names with search_dbt_column_names to find relevant models and columns.
• Search within compiled SQL code using search_dbt_sql_code to discover where a node's SQL appears.
• Get detailed attributes for a node with get_dbt_node_attributes by its unique ID.
• Find direct upstream dependencies (predecessors) with get_dbt_predecessors and direct downstream dependents (successors) with get_dbt_successors.
• Trace column-level lineage with get_column_ancestors to identify all upstream sources for a column and get_column_descendants to identify all downstream dependents for a column.

Available tools

search_dbt_node_names

Search for dbt nodes by name to locate models, sources, tests, and other nodes.

search_dbt_column_names

Search for nodes based on column names to quickly find relevant models and columns.

search_dbt_sql_code

Search within the compiled SQL code of nodes to understand how queries are constructed.

get_dbt_node_attributes

Retrieve detailed attributes for a node using its unique ID.

get_dbt_predecessors

Find direct upstream dependencies (predecessors) of a node.

get_dbt_successors

Find direct downstream dependents (successors) of a node.

get_column_ancestors

Trace all upstream sources for a specific column in a model.

get_column_descendants

Trace all downstream dependents of a specific column in a model.