dbt-doctor MCP
dbt-doctor scores a dbt project's health, profiles models, detects schema drift and writes documentation into schema.yml.
- 105 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The server reads warehouse tables and edits the project's `schema.yml`.
Install
- Works in
Manual install
{
"mcpServers": {
"dbt-doctor": {
"command": "dbt-doctor",
"args": ["--project-dir", "/absolute/path/to/your/dbt/project"]
}
}
}The block for `claude_desktop_config.json` from the README. First `pip install dbt-doctor` and `dbt compile`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The server reads warehouse tables and edits the project's `schema.yml`.
This is third-party code. Review the repository files before installing.
What it does
dbt-doctor is an MCP server that gives an agent context about a dbt project. It reads `manifest.json`, queries the warehouse and explains where tests and descriptions are missing. A project score of 0 to 100 percent weighs documentation, tests and naming, and a model ranking shows which are covered worst. Profiling computes NULL rates, cardinality, min and max, and uniqueness with one batched SQL query per table. The statistics turn into suggestions for `not_null`, `unique` and `accepted_values` tests. Comparing the warehouse with the manifest finds added, removed and type-changed columns. Writing to `schema.yml` through `ruamel.yaml` keeps comments and manual settings and appends only what is missing, with a diff preview. There are twelve tools, including `audit_project`, `profile_model`, `detect_schema_drift`, `suggest_tests` and `update_model_yaml`.
Who it is for. Analytics engineers on dbt who need to spot gaps in tests and descriptions fast and close them through an agent.
Good fit when
- Before a release a score of model coverage by tests and descriptions is needed.
- The difference between warehouse columns and the manifest must be found.
- An undocumented model should be described from real data.
- Orphan models and nodes with high fan-out are suspected in the project.
Not a fit when
- dbt commands must be executed; the official `dbt-mcp` exists for that.
- The agent must not touch warehouse data.
- Production-grade support without caveats is required.
Example request
Score the dbt project's health, show the five worst-covered models and suggest tests for the weakest without writing them to files.MCP
- Transport
- stdio
- Authentication
- not required
Limitations
The author calls the project an active alpha and keeps a limitations list in `KNOWN_LIMITATIONS.md` and `STATUS.md`; the README snapshot date points to late 2025. `dbt compile` must run first so `target/manifest.json` exists. Warehouse queries are read-only inside a transaction, yet profiling still reads real tables. Writing to `schema.yml` shows a diff before applying, but commit your files to Git before trying it.
How to disable. Remove the `dbt-doctor` entry from the MCP client configuration and, if you like, run `pip uninstall dbt-doctor`.
FAQ
How do I install it?
Run `pip install dbt-doctor`, then add the server to the client configuration with `--project-dir` pointing at the project path.
What is needed before the first run?
Run `dbt compile` so the `target/manifest.json` that the server parses exists.
Is `execute_query` safe?
Queries run in a read-only transaction and table and column names are checked against an allowlist.
Will it wipe my YAML comments?
No, writing through `ruamel.yaml` keeps comments, tests and formatting and appends only what is missing.
How is it different from dbt-mcp?
`dbt-mcp` runs dbt commands, while dbt-doctor focuses on audit, profiling, schema drift and documentation.
Discussion
No questions or reviews yet.
Related
MCP serversdbt MCP
dbt-mcp
The official MCP server from dbt Labs: the Semantic Layer, project metadata, dbt commands and SQL against the warehouse from an agent
Ragstar answers questions about a dbt project in chat and Slack, and its MCP server gives Claude search over models and their SQL
dbt Charts
dbt-charts
Declarative YAML on top of SQL for dashboards: you describe how to show data, agents write YAML, people audit. The dbt-charts package and the dct CLI, beta
The Dex plugin: an agent explores a database, builds dbt models and a semantic layer and tracks schema drift under cost control
dbt Agent Skills
dbt-agent-skills
Official dbt Labs skills: the agent understands dbt projects, runs workflows and helps with migration
An agent queries GreptimeDB metrics, logs and traces with SQL, TQL and RANGE, with write protection and data masking
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| dbt-doctor (this card) | no | not required | 105 | |
| dbt MCP | yes | API key | 621 | runs dbt commands; dbt-doctor handles audit, profiling and documentation writing |
| dbt Agent Skills | yes | 762 | a skill set for working with dbt; dbt-doctor adds MCP analysis tools |
README in short
The server combines project audit, data profiling, schema drift and safe documentation writing into one tool set.