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

@us-all/dbt-mcp

dbt MCP-сервер — manifest.json, run_results.json, sources.json, catalog.json, а также таблицы результатов DQ (BigQuery / Postgres) через один stdio MCP. Построен на базе @us-all/mcp-toolkit.

Окно с правами только на чтение в ваш dbt-проект для LLM-клиентов. Никакого запуска dbt run — только глубокая интроспекция, анализ истории запусков, актуальность источников, покрытие тестами по столбцам, анализ цепочек зависимостей и (если у вас есть пользовательская таблица результатов DQ) исторические тренды проверок и статус SLA по уровням (Tier).

Для запуска DAG / истории запусков / просмотра логов установите вместе с ним @us-all/airflow-mcp.

  • 22 инструмента в 3 категориях (dbt, quality, meta)

  • 4 MCP-промпта для рабочих процессов триажа

  • 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 для использования потоковой передачи по 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

Промпты

Промпт

Использовать, когда

investigate-failed-tests

«Что сломалось за последние 24 часа?»

freshness-degradation-triage

«Есть ли устаревшие источники?» (опционально фокус на Tier 1)

dq-trend-report

«Составь отчет о трендах DQ для стейкхолдеров»

incident-triage

«Триаж <model

source>» — объединяет все сигналы

Переменные окружения

Переменная

Обязательно

Примечания

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

нет

Полное имя таблицы проверок (без него категория quality выдаст ошибку при вызове)

DQ_SCORE_TABLE

нет

Полное имя таблицы ежедневных оценок

GOOGLE_APPLICATION_CREDENTIALS

нет

Для бэкенда BigQuery (поддерживается fallback на ADC)

BQ_PROJECT_ID

нет

Явный ID проекта BQ (иначе определяется из ADC)

PG_CONNECTION_STRING

нет

Когда DQ_BACKEND=postgres (секрет)

DBT_ALLOW_WRITE

нет

Зарезервировано для будущих инструментов записи (в v0.1 отсутствуют)

DBT_TOOLS / DBT_DISABLE

нет

Переключатели категорий

Предполагаемая схема таблицы результатов DQ (v0.1)

Категория quality предполагает наличие столбцов check_name, check_type, dataset, table_name, status, severity, failure_count, run_at, message в DQ_RESULTS_TABLE, а также score_date, scope, tier, completeness_pct, freshness_pct, validity_pct, anomaly_free_pct, overall_score в DQ_SCORE_TABLE. В v0.2 будет добавлен настраиваемый слой сопоставления столбцов.

Протестированные схемы

  • dbt manifest schema 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