@us-all/dbt-mcp

dbt MCP 服务器 — 通过一个 stdio MCP 接口提供 manifest.json、run_results.json、sources.json、catalog.json 以及 DQ（数据质量）结果表（BigQuery / Postgres）。基于 @us-all/mcp-toolkit 构建。

为 LLM 客户端提供一个查看 dbt 项目的只读窗口。无需触发 dbt run — 仅提供深度内省、运行历史分析、源新鲜度、列级测试覆盖率、血缘关系遍历，以及（如果您有自定义的 DQ 结果表）历史检查趋势和层级 SLA 状态。

如需 DAG 触发 / 运行历史 / 日志追踪，请同时安装配套的 @us-all/airflow-mcp。

• 涵盖 3 个类别的 22 个工具 (dbt, quality, meta)

• 4 个用于分类工作流的 MCP Prompts

• 4 个聚合工具，可替代 3-5 次“列出 / 获取 / 列出”的往返调用

• 默认只读

• 混合后端：BigQuery（默认）或 Postgres 用于 DQ 结果表 — 两者均按需导入

安装

# 1. add the MCP server
pnpm add -D @us-all/dbt-mcp
# 2. add the DQ backend you actually use (only if you query custom DQ tables):
pnpm add -D @google-cloud/bigquery   # OR
pnpm add -D pg

运行

DBT_PROJECT_DIR=/path/to/dbt-project \
DQ_RESULTS_TABLE=my-project.data_ops.quality_checks \
npx @us-all/dbt-mcp

该服务器使用 MCP stdio 协议；将其连接到 Claude Desktop / Cursor / 任何 MCP 客户端。设置 MCP_TRANSPORT=http 可选择使用 Streamable HTTP 传输（Bearer 认证，/health 端点）。

类别

使用 DBT_TOOLS=dbt（允许列表）或 DBT_DISABLE=quality（禁用列表）进行切换。

工具概览

dbt (15 + 2)

dbt-list-models, dbt-get-model, dbt-list-tests, dbt-get-test, dbt-list-sources, dbt-get-source, dbt-list-exposures, dbt-list-macros, dbt-get-macro, dbt-list-runs, dbt-get-run-results, dbt-failed-tests, dbt-slow-models, dbt-coverage, dbt-graph, freshness-status, incident-context

quality (5 + 2)

dq-list-checks, dq-get-check-history, dq-failed-checks-by-dataset, dq-score-trend, dq-tier-status, failed-tests-summary, dq-score-snapshot

Prompts

环境变量

DQ 结果表假设架构 (v0.1)

quality 类别假设 DQ_RESULTS_TABLE 包含 check_name, check_type, dataset, table_name, status, severity, failure_count, run_at, message 列；假设 DQ_SCORE_TABLE 包含 score_date, scope, tier, completeness_pct, freshness_pct, validity_pct, anomaly_free_pct, overall_score 列。v0.2 将增加可配置的列映射层。

已测试架构

• dbt manifest 架构 v11 / v12 / v13（其他版本通常可以解析，但会显示 caveats 行进行提示）

配套服务器

如需 Airflow DAG 操作（列出、运行、任务实例、日志追踪、触发、清除），请与此服务器一起安装 @us-all/airflow-mcp。

构建

pnpm install
pnpm run build      # tsc → dist/
pnpm test           # vitest
pnpm run smoke      # spawns dist/index.js, calls initialize + tools/list (set env first)

许可证

MIT — 参见 LICENSE。