Skip to main content
Glama
@us-all/dbt-mcp
by us-all

@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

Related MCP server: dbt-mcp

运行

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

15 + 2 个聚合工具

解析 manifest.json / run_results.json / sources.json / catalog.json

quality

5 + 2 个聚合工具

查询 quality_checks 和 quality_score_daily (BQ 或 PG)

meta

1 (始终开启)

用于自然语言工具发现的 search-tools

使用 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

Prompt

使用场景

investigate-failed-tests

“过去 24 小时内有什么故障?”

freshness-degradation-triage

“有数据源过期了吗?”(可选关注 Tier 1)

dq-trend-report

“给我一份利益相关者友好的 DQ 趋势报告”

incident-triage

“分类 <模型

源>” — 汇总所有信号

环境变量

环境变量

必需

说明

DBT_PROJECT_DIR

是

dbt 项目根目录 (dbt_project.yml 所在位置)

DBT_TARGET_DIR

否

默认为 $DBT_PROJECT_DIR/target

DBT_RUN_HISTORY_DIR

否

用于存档 run_results.json 历史记录的可选目录

DQ_BACKEND

否

bigquery (默认) 或 postgres

DQ_RESULTS_TABLE

否

检查表的 FQN(没有它,quality 类别在调用时会报错)

DQ_SCORE_TABLE

否

每日评分表的 FQN

GOOGLE_APPLICATION_CREDENTIALS

否

用于 BigQuery 后端(支持 ADC 回退)

BQ_PROJECT_ID

否

显式 BQ 项目(否则从 ADC 推断)

PG_CONNECTION_STRING

否

当 DQ_BACKEND=postgres 时使用(敏感信息)

DBT_ALLOW_WRITE

否

为未来的写入工具预留(v0.1 中暂无)

DBT_TOOLS / DBT_DISABLE

否

类别切换

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。

Available Tools

27 tools
dbt-coverageA

Per-column test coverage for a dbt model (which columns have tests, table-level tests, coverage %)

Inputs: name, uniqueId, extractFields.

dbt-failed-testsB

Find tests that failed across the last N runs, grouped and ordered by chronic failure count

Inputs: recentRuns, extractFields.

dbt-get-macroA

Get a dbt macro: signature, raw SQL, and reverse-lookup of nodes that call it

Inputs: name, uniqueId, extractFields.

dbt-get-modelA

Get a single dbt model: refs, sources, columns (with catalog types if available), attached tests, raw/compiled SQL

Inputs: name, uniqueId, extractFields, includeCompiledSql.

dbt-get-run-resultsB

Get per-node results from a specific dbt invocation (or the latest run if invocationId omitted)

Inputs: limit, status, invocationId, extractFields.

dbt-get-sourceA

Get a single dbt source: freshness criteria, columns, latest freshness result from sources.json

Inputs: uniqueId, tableName, sourceName, extractFields.

dbt-get-testA

Get a single dbt test: definition, parameters, attached models, latest run result

Inputs: uniqueId (required), extractFields.

dbt-graphB

Walk dbt parent_map / child_map to return upstream and downstream nodes (model/source/test) up to a given depth

Inputs: name, uniqueId, extractFields, upstreamDepth, +1 more.

dbt-list-exposuresA

List dbt exposures (downstream BI/ML/application consumers declared in YAML)

Inputs: limit, search, exposureType, extractFields.

dbt-list-macrosA

List dbt macros from manifest.json with package / name filters

Inputs: limit, search, package, extractFields.

dbt-list-modelsA

List dbt models from manifest.json with filters (package, tag, materialized, schema, name search)

Inputs: tag, limit, schema, search, +3 more.

dbt-list-runsC

List recent dbt invocations from run_results.json files in target/ and DBT_RUN_HISTORY_DIR

Inputs: limit, extractFields.

dbt-list-sourcesC

List dbt sources from manifest.json with optional source-group / name filters

Inputs: limit, search, sourceName, extractFields.

dbt-list-testsC

List dbt tests (generic or singular) optionally filtered to a specific model

Inputs: limit, search, testKind, attachedTo, +1 more.

dbt-sla-statusB

Compare latest dbt run test pass rate and source freshness pass rate against DBT_SLA_CONFIG_PATH thresholds (dbt_sla.test_pass_pct / freshness_pass_pct). Returns per-axis passPct/target/meeting plus caveats when SLA fields or artifacts are missing.

Inputs: extractFields.

dbt-slow-modelsB

Top N slowest models in a dbt run by execution_time, with bytes_processed when available

Inputs: topN, invocationId, extractFields.

dq-failed-checks-by-datasetB

Group failing checks by dataset across a recent window with the latest 5 failures per dataset

Inputs: topN, sinceHours, extractFields.

dq-get-check-historyC

Time-series of one check_name's status across the last N days

Inputs: checkName (required), days, limit, extractFields.

dq-list-checksA

List recent rows from DQ_RESULTS_TABLE filtered by dataset / status / type / time window

Inputs: type, limit, status, dataset, +2 more.

dq-score-snapshotA

Aggregated 4-axis score trend + today's Tier compliance + most recent failing checks. Combines dq-score-trend + dq-tier-status + dq-list-checks(fail).

Inputs: days, extractFields, includeFailing.

dq-score-trendB

Time-series of the 4-axis DQ score (completeness / freshness / validity / anomaly_free) plus overall_score from DQ_SCORE_TABLE

Inputs: days, scope, extractFields.

dq-tier-by-sourceA

Per-tier rollup computed from quality_checks grouped by source. Reads source-to-tier mapping from dbt sources.yml meta.tier and tier targets from DBT_SLA_CONFIG_PATH (falls back to defaults). Reports per-source pass rate, meeting/missing per tier, and untiered sources as caveats.

Inputs: date, mode, sinceHours, sourceFilter, +1 more.

dq-tier-statusA

Compare today's overall_score per scope against Tier SLA targets (defaults Tier 1 99.5 / 2 99.0 / 3 95.0; override via DBT_SLA_CONFIG_PATH yaml or DQ_TIER1_TARGET_PCT) and report meeting vs missing counts

Inputs: date, extractFields, fallbackMaxDays.

failed-tests-summaryA

Aggregated 24h-ish view: dbt failed tests + DQ checks failures grouped by dataset + most recent failing rows. Replaces 3+ tool calls (dbt-failed-tests + dq-failed-checks-by-dataset + dq-list-checks).

Inputs: recentRuns, sinceHours, extractFields.

freshness-statusB

Cross-reference dbt source freshness criteria with sources.json results in a single 'is anything stale right now?' answer.

Inputs: failingOnly, extractFields.

incident-contextA

Single asset deep-dive: dbt definition + recent test failures + DQ checks for the dataset. Designed to anchor an LLM-driven incident triage.

Inputs: modelName, sourceFqn, sinceHours, extractFields.

search-toolsA

Discover available dbt MCP tools by natural language query across dbt / quality / meta categories.

Inputs: query (required), limit, category.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools have distinct purposes, but composite tools like `failed-tests-summary` overlap with `dbt-failed-tests` and `dq-failed-checks-by-dataset`, and `incident-context` aggregates multiple individual tools, potentially causing confusion about which to use.

    Naming Consistency3/5

    Tools follow a consistent prefix pattern (`dbt-` and `dq-`) but there are deviations like `dbt-graph` instead of `dbt-get-graph`, and four tools without any prefix (`failed-tests-summary`, `freshness-status`, `incident-context`, `search-tools`), mixing naming conventions.

    Tool Count4/5

    With 27 tools covering dbt core operations, data quality, and incident triage, the count is slightly high but well-justified for the broad scope, avoiding the extremes of overwhelming or insufficient coverage.

    Completeness4/5

    The tool set covers essential dbt monitoring and data quality workflows (listing, details, failures, SLAs, scores), but lacks write operations and some administrative functions, though that seems intentional for a read-only analysis server.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      AI-driven MCP server that audits, profiles, detects schema drift, and auto-generates documentation for dbt projects, enabling natural language interaction with your dbt project's health.
      105
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides tools to interact with dbt, including dbt Core, Cloud CLI, Semantic Layer, and Discovery API.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A production-ready MCP server that provides comprehensive dbt project quality assessment for any GitHub repository, enabling AI agents to analyze dbt models, check metadata coverage, and map data lineage.
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing read-only Snowflake metadata tools (schemas, tables, queries, lineage) for agentic data pipeline generation, enabling natural-language-to-pipeline workflows with dbt, Airflow, and Great Expectations.
      1
      MIT