What is Dbt Docs Mcp

dbt-docs-mcp is a Model Context Protocol (MCP) server designed for interacting with dbt project metadata, specifically dbt Docs artifacts such as ‘manifest.json’ and ‘catalog.json’. It exposes dbt graph information and allows users to query node details, model/column lineage, and related metadata.

Use cases

Use cases for dbt-docs-mcp include data lineage tracking, model dependency analysis, and metadata exploration. It can assist data teams in debugging issues, optimizing data workflows, and ensuring data quality by providing insights into model relationships and column dependencies.

How to use

To use dbt-docs-mcp, ensure Python is installed along with the ‘uv’ package. Clone the repository and navigate to the dbt-docs-mcp directory. Optionally, you can parse the dbt manifest for column-level lineage by setting up the required Python environment and running the provided script with the path to your dbt manifest and catalog.

Key features

Key features of dbt-docs-mcp include searching dbt nodes by name, column names, and SQL code; inspecting node attributes; exploring lineage with upstream and downstream dependencies; and tracing column-level lineage. Suggested extensions include executing SQL queries and retrieving metadata directly from the database.

Where to use

dbt-docs-mcp can be used in data engineering, analytics, and business intelligence fields where dbt is employed for data transformation and documentation. It is particularly useful for teams that need to understand and manage complex data models and their relationships.

dbt-docs-mcp

Model Context Protocol (MCP) server for interacting with dbt project metadata, including dbt Docs artifacts (manifest.json, catalog.json). This server exposes dbt graph information and allows querying node details, model/column lineage, and related metadata.

Key Functionality

This server provides tools to:

• Search dbt Nodes:
  • Find nodes (models, sources, tests, etc.) by name (search_dbt_node_names).
  • Locate nodes based on column names (search_dbt_column_names).
  • Search within the compiled SQL code of nodes (search_dbt_sql_code).
• Inspect Nodes:
  • Retrieve detailed attributes for any given node unique ID (get_dbt_node_attributes).
• Explore Lineage:
  • Find direct upstream dependencies (predecessors) of a node (get_dbt_predecessors).
  • Find direct downstream dependents (successors) of a node (get_dbt_successors).
• Column-Level Lineage:
  • Trace all upstream sources for a specific column in a model (get_column_ancestors).
  • Trace all downstream dependents of a specific column in a model (get_column_descendants).
• Suggested extensions:
  • Tool that allows executing SQL queries.
  • Tool that retrieves table/view/column metadata directly from the database.
  • Tool to search knowledge-base.

Getting Started

1. Prerequisites: Ensure you have Python installed and uv
2. Clone the repo:

   git clone <repository-url>
   cd dbt-docs-mcp
   

3. Optional: parse dbt manifest for column-level lineage:
   • Setup the required Python environment, e.g.:

   uv sync
   

   • Use the provided script scripts/create_manifest_cl.py and simply provide the path to your dbt manifest, dbt catalog and the desired output paths for your schema and column lineage file:

   python scripts/create_manifest_cl.py --manifest-path PATH_TO_YOUR_MANIFEST_FILE --catalog-path PATH_TO_YOUR_CATALOG_FILE --schema-mapping-path DESIRED_OUTPUT_PATH_FOR_SCHEMA_MAPPING --manifest-cl-path DESIRED_OUTPUT_PATH_FOR_MANIFEST_CL
   

   • Depending on your dbt project size, creating column-lineage can take a while (hours)
4. Run the Server:
   • If your desired MCP client (Claude desktop, Cursor, etc.) supports mcp.json it would like as below:

   {
     "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"
         }
       }
     }
   }