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 기반으로 구축되었습니다.

LLM 클라이언트를 위한 dbt 프로젝트의 읽기 전용 창입니다. dbt run을 트리거하지 않으며, 심층적인 인트로스펙션, 실행 이력 분석, 소스 신선도, 컬럼별 테스트 커버리지, 계보 탐색, 그리고 (사용자 정의 DQ 결과 테이블이 있는 경우) 과거 체크 추세 및 티어 SLA 상태를 제공합니다.

DAG 트리거 / 실행 이력 / 로그 테일링을 위해서는 **@us-all/airflow-mcp**를 함께 설치하세요.

  • 3개 카테고리(dbt, quality, meta)에 걸친 22개의 도구

  • 트리아주 워크플로우를 위한 4개의 MCP 프롬프트

  • "목록 조회 / 가져오기 / 목록 조회"의 3~5회 왕복을 대체하는 4개의 집계 도구

  • 기본적으로 읽기 전용

  • 하이브리드 백엔드: DQ 결과 테이블을 위한 BigQuery(기본값) 또는 Postgres — 둘 다 필요할 때 지연 로드됨

설치

# 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 클라이언트에 연결하세요. Streamable HTTP 전송(Bearer 인증, /health 엔드포인트)을 선택하려면 MCP_TRANSPORT=http를 설정하세요.

카테고리

카테고리

도구

목적

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

"오래된 소스가 있나요?" (티어 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

아니오

체크 테이블의 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 매니페스트 스키마 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