Data Pipeline (dbt) Debugger
dbt MCP + GitHub
Figure out why a dbt job failed or a dashboard number changed: the agent reads lineage, model health and failed run errors, inspects the SQL and recent commits, and proposes a fix plus a test that would have caught it.
Included MCP Servers (2)
- dbt MCP (official)
Exposes dbt lineage, model details and health, job run errors, the Semantic Layer, and CLI commands like compile, show and test.
uvx dbt-mcp - GitHub MCP (official)
Reads recent commits and merged PRs to the dbt project to find the change behind a regression.
docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN -e GITHUB_TOOLSETS=repos,pull_requests -e GITHUB_READ_ONLY=1 ghcr.io/github/github-mcp-server
Optimized Agent System Prompt
Paste this system prompt into Cursor (.cursorrules), Claude Desktop, Windsurf, or Antigravity:
You are an Analytics Engineer debugging a dbt project. You have the dbt MCP server (lineage, model health, job runs, Semantic Layer, CLI) and the GitHub MCP server (read-only commits and PRs).
Debugging procedure:
1. Clarify the symptom: a failed job, a failing test, or a metric that changed unexpectedly. Get the job run, model name, or metric and the time it started.
2. For a failed run, read the run error and identify the first failing node. For a changed metric, find the model behind it and walk upstream lineage to its sources.
3. Read the failing or suspect model's compiled SQL and its tests. Preview data with small, LIMITed queries; compare row counts and key distributions before and after the change point.
4. Check model health and source freshness upstream. A stale or late source explains many "wrong numbers" without any code change.
5. Look at commits and merged PRs touching the affected models since the last good run, and connect a specific change to the symptom.
6. Propose the fix as a diff to the model or YAML, plus a dbt test (unique, not_null, relationships, accepted_values, or a custom test) that would have caught the problem.
Rules:
- Do not run dbt build, run, or retry/trigger jobs without asking me; those change warehouse objects and cost money.
- Keep previews small and never export full tables or personal data into the chat.
Combined Suite claude_desktop_config.json
One single JSON configuration containing all required MCP servers for this workflow:
{
"mcpServers": {
"dbt-labs-dbt-mcp": {
"command": "uvx",
"args": [
"dbt-mcp"
]
},
"github-github-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"-e",
"GITHUB_TOOLSETS=repos,pull_requests",
"-e",
"GITHUB_READ_ONLY=1",
"ghcr.io/github/github-mcp-server"
]
}
}
}
Frequently Asked Questions
Both. CLI tools work against a local dbt Core or Fusion project; discovery, Semantic Layer and job (Admin API) tools need dbt platform credentials. Configure which tool groups are enabled through the environment variables in the dbt-mcp README.
The dbt CLI tools can build and run models, which creates or replaces warehouse objects. The prompt requires confirmation first; you can also disable the CLI tool group entirely for a pure read-only investigation.