by Astoriel
AI-driven quality & governance MCP Server for dbt projects. Audit coverage, profile data, detect schema drift, and auto-generate documentation — all through natural language with your AI assistant.
# Add to your Claude Code skills
git clone https://github.com/Astoriel/dbt-doctordbt-doctor is a Model Context Protocol (MCP) server that provides your AI coding assistant with deep context regarding your dbt project's health. Instead of manually running CLI commands and analyzing outputs, you can interact with your AI:
The tool handles the heavy operations—reading the manifest, profiling your data warehouse, detecting schema drift, and writing back to schema.yml files—without requiring you to leave the chat.
Note: This tool is designed to complement the official dbt-labs/dbt-mcp. While dbt-labs/dbt-mcp focuses on running dbt commands, dbt-doctor focuses on auditing, profiling, and documentation.
Evaluate your project with a 0–100% score based on documentation, testing, and naming conventions. Access a ranked list of models lacking coverage to prioritize your efforts.
Perform efficient single-pass column statistics—including NULL rates, cardinality, min/max values, and uniqueness—using one batched SQL query per table to avoid slow row-by-row scanning.
Compare the current state of your data warehouse against the definitions in your manifest.json. Instantly identify added, removed, or type-changed columns.
Translate profiling statistics into actionable dbt test recommendations. For example, a uniquely populated column without nulls will prompt suggestions for not_null and unique tests, while low cardinality will suggest accepted_values with predefined options.
No comments yet. Be the first to share your thoughts!
Update schema.yml files using ruamel.yaml to retain hand-written comments, existing tests, and formatting. The tool only appends missing information and preserves your manual configurations.
Execute a complete workflow in a single conversational turn: profile a model, suggest tests, preview changes, and write to schema.yml.
| Category | Tool | Description |
|---|---|---|
| Context | list_models | Overview of all models and their coverage status |
| Context | get_model_details | Detailed model information including SQL, columns, lineage, and tests |
| Audit | audit_project | Project health score and naming convention violations |
| Audit | check_test_coverage | Models ranked by their test coverage percentage |
| Audit | analyze_dag | Detection of orphan models and high fan-out nodes |
| Audit | get_project_health | Single-call dashboard summarizing project status |
| Profiling | profile_model | Batched column statistics |
| Profiling | execute_query | Read-only SQL execution against your warehouse |
| Profiling | detect_schema_drift | Comparison of database columns against manifest definitions |
| Generation | suggest_tests | Translation of profile data into dbt test recommendations |
| Generation | update_model_yaml | Safe merging of documentation and tests to schema.yml |
| Generation | generate_model_docs | Complete end-to-end documentation workflow |
pip install dbt-doctor
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"dbt-doctor": {
"command": "dbt-doctor",
"args": ["--project-dir", "/absolute/path/to/your/dbt/project"]
}
}
}
Add the following to your .cursor/mcp.json:
{
"mcpServers": {
"dbt-doctor": {
"command": "dbt-doctor",
"args": ["--project-dir", "/absolute/path/to/your/dbt/project"]
}
}
}
Prerequisite: Run dbt compile prior to usage to ensure target/manifest.json is available for dbt-doctor to parse.
The application connects the AI Assistant with your dbt project and database through the MCP protocol. It features a read-only analysis layer combined with a secure generation toolkit that merges changes seamlessly into your existing YAML schemas.
execute_query operations operate within a read-only transaction. Write processes are restricted at the database connector level.schema.yml, ensuring you retain control over modifications.| Project | Description | |---|---| | dbt-labs/dbt-mcp | Official MCP focused on dbt command execution | | dbt-coverage | CLI tool for coverage reporting without AI integration | | dbt-project-evaluator | dbt package for project evaluation, requiring installation per project |
dbt-doctor uniquely consolidates auditing, profiling, drift detection, and AI-driven YAML updates into a single server interface.
MIT — see the LICENSE file.