@us-all/dbt-mcp
@us-all/dbt-mcp
dbt MCPサーバー —
manifest.json、run_results.json、sources.json、catalog.json、およびDQ結果テーブル(BigQuery / Postgres)を1つのstdio MCPで提供します。@us-all/mcp-toolkitをベースに構築されています。
LLMクライアント向けにdbtプロジェクトを読み取り専用で公開します。dbt runをトリガーするのではなく、詳細なイントロスペクション、実行履歴分析、ソースの鮮度確認、列ごとのテストカバレッジ、リネージの追跡、および(カスタムDQ結果テーブルがある場合)履歴チェックの傾向やTier 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 pgRelated 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エンドポイント)を選択できます。
カテゴリ
カテゴリ | ツール | 目的 |
| 15 + 2 集約 |
|
| 5 + 2 集約 |
|
| 1 (常時有効) | 自然言語によるツール探索のための |
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
プロンプト
プロンプト | 使用タイミング | |
| 「過去24時間で何が壊れていますか?」 | |
| 「古いソースはありますか?」 (Tier 1に絞ることも可能) | |
| 「ステークホルダー向けのDQ傾向レポートを作成して」 | |
| 「<model | source> をトリアージして」 — すべてのシグナルを統合 |
環境変数
環境変数 | 必須 | 備考 |
| はい | dbtプロジェクトのルート ( |
| いいえ | デフォルトは |
| いいえ | アーカイブされた |
| いいえ |
|
| いいえ | チェックテーブルのFQN (これがない場合、 |
| いいえ | スコア日次テーブルのFQN |
| いいえ | BigQueryバックエンド用 (ADCフォールバックをサポート) |
| いいえ | 明示的なBQプロジェクト (指定がない場合はADCから推論) |
| いいえ |
|
| いいえ | 将来の書き込みツール用に予約 (v0.1ではなし) |
| いいえ | カテゴリの切り替え |
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 toolsdbt-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
Scored across 27 tools
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.
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.
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.
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
Related MCP Connectors
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAI-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.105MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that provides tools to interact with dbt, including dbt Core, Cloud CLI, Semantic Layer, and Discovery API.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA 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.8MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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.1MIT