dbt

@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）にまたがる 27 個のツール — プリミティブツール 21 個、集約ツール 5 個、メタツール 1 個
• トリアージのワークフロー向け MCP プロンプト 4 個
• 「list / get / list」の 3〜5 回のラウンドトリップを置き換える集約ツール 5 個
• 大量データの読み取りに対応したextractFieldsレスポンスプロジェクション
• デフォルトで読み取り専用
• ハイブリッドバックエンド：BigQuery（デフォルト）、または DQ 結果テーブル用の 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

実行

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 + 集約ツール 3 個	manifest.json／run_results.json／sources.json／catalog.jsonを解析
quality	6 + 集約ツール 2 個	quality_checksとquality_score_dailyをクエリ（BQ または PG）。dq-tier-by-sourceで Tier ごとに集計
meta	1（常時有効）	自然言語でツールを見つけるためのsearch-tools

DBT_TOOLS=dbt（許可リスト）またはDBT_DISABLE=quality（拒否リスト）で切り替えます。

ツールの概要

dbt（15 + 3）

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、dbt-sla-status

quality（6 + 2）

dq-list-checks、dq-get-check-history、dq-failed-checks-by-dataset、dq-score-trend、dq-tier-status、dq-tier-by-source、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	いいえ	チェックテーブルの FQN。チェックベースの品質ツールでのみ必須です
DQ_SCORE_TABLE	いいえ	日次スコアテーブルの FQN。スコア専用ツールで必須です
GOOGLE_APPLICATION_CREDENTIALS	いいえ	BigQuery バックエンド用（ADC へのフォールバックに対応）
BQ_PROJECT_ID	いいえ	明示的な BQ プロジェクト（指定しない場合は ADC から推定されます）
PG_CONNECTION_STRING	いいえ	DQ_BACKEND=postgres の場合に使用します（シークレット）
DQ_SCHEMA	いいえ	generic（デフォルト）または us-all — quality カテゴリの基本スキーマプリセットです
DQ_COL_*	いいえ	DQ_SCHEMA に対する列ごとの上書き設定（以下を参照）。上書き値には単純な SQL 識別子を指定する必要があります。
DQ_TIER1_TARGET_PCT	いいえ	tier 列が設定されていない場合の dq-tier-status の Tier 1 SLA 閾値（デフォルトは 99.5）。両方が設定されている場合は、DBT_SLA_CONFIG_PATH の tier_sla.1 が優先されます。
DBT_SLA_CONFIG_PATH	いいえ	tier_sla ブロックと dbt_sla ブロックを含む任意の YAML パスです。dq-tier-status の閾値と、dq-tier-by-source のティアごとの目標値を設定します。更新時刻をキャッシュします。
DBT_ALLOW_WRITE	いいえ	将来の書き込みツール用に予約されています（現在はありません）
DBT_TOOLS / DBT_DISABLE	いいえ	カテゴリの切り替え

DQ 結果テーブルのスキーマ形式

quality カテゴリは、DQ_SCHEMA によって 2 つのスキーマプリセットをサポートします。

DQ_SCHEMA=generic（デフォルト）

DQ_RESULTS_TABLE にあると想定される列：run_at、check_name、check_type、dataset、table_name、status、severity、failure_count、message。

DQ_SCORE_TABLE にあると想定される列：score_date、scope、tier、completeness_pct、freshness_pct、validity_pct、anomaly_free_pct、overall_score。

dq-tier-status は、scope ごとの行に基づいて Tier 1/2/3 を集計します。

DQ_SCHEMA=us-all

us-all で使用されている実際のスキーマ（Postgres の data_ops データベース）：

quality_checks：run_date、check_type、dimension、source、target_name、status、metric_value、threshold、details (JSONB)。

quality_score_daily：run_date、completeness_pct、freshness_pct、validity_pct、anomaly_free_pct、overall_score、total_checks、failed_checks。

この形式では、quality_score_daily は 1 日につき 1 行です（scope ごとの集計はなく、tier 列もありません）。dq-tier-status は、当日の overall_score を DQ_TIER1_TARGET_PCT（デフォルトは 99.5）と比較する方式にフォールバックします。

dq-get-check-history では、us-all にネイティブの check_name 列がないため、checkName を '<check_type>:<target_name>' の形式で指定する必要があります。

列ごとの上書き — DQ_COL_*

DQ テーブルがどちらのプリセットにも一致しない場合は、DQ_SCHEMA に列ごとの上書きを追加してください。DQ_COL_* 環境変数が設定されている場合、その列だけプリセット値を置き換えます。未設定の変数には、プリセットのデフォルト値が使われます。

環境変数を通じて生の SQL が挿入されるのを防ぐため、上書き値は単純な SQL 識別子として検証されます。DQ_RESULTS_TABLE／DQ_SCORE_TABLE のテーブル名も、設定されたバックエンドに合わせて検証され、引用符で囲まれます。

環境変数	論理的な概念	汎用プリセット	us-all プリセット
DQ_COL_RUN_AT	チェックテーブル上のタイムスタンプ／日付	run_at	run_date
DQ_COL_CHECK_TYPE	チェック種別／ディメンション群	check_type	check_type
DQ_COL_STATUS	成功／失敗／警告／エラー	status	status
DQ_COL_DATASET	データセット／ソース／スキーマ	dataset	source
DQ_COL_TABLE_NAME	テーブル名または対象名	table_name	target_name
DQ_COL_SEVERITY	重大度／ディメンション	severity	dimension
DQ_COL_FAILURE_COUNT	数値の失敗件数／メトリクス	failure_count	metric_value
DQ_COL_MESSAGE	フリーテキストまたは JSON メッセージ	message	details::text
DQ_COL_CHECK_NAME	チェックの自然識別子	check_name	(なし)
DQ_COL_SCORE_DATE	スコアテーブルの日付列	score_date	run_date
DQ_COL_SCOPE	スコアテーブルのスコープ／テナント列	scope	(なし)
DQ_COL_TIER	スコアテーブルのティア列	tier	(なし)

NULL を許容する 3 つの列（DQ_COL_CHECK_NAME、DQ_COL_SCOPE、DQ_COL_TIER）については、値に none／null／- を設定すると、「ネイティブ列なし」と宣言できます。

• check_name がない場合 → ツールは check_type || ':' || table_name から値を合成します。その場合、dq-get-check-history は checkName が '<check_type>:<table_name>' の形式であることを想定します。
• scope がない場合 → dq-score-trend の scope フィルターは無視され（ただし注意点があります）、dq-tier-status は DQ_TIER1_TARGET_PCT と比較する単一の overall_score パスに切り替わります。
• tier がない場合 → 同じ単一の overall_score フォールバックが適用されます。

例 — 列名が異なる Postgres スキーマで汎用プリセットを使用する場合：

DQ_SCHEMA=generic
DQ_COL_RUN_AT=checked_at
DQ_COL_DATASET=schema_name
DQ_COL_TABLE_NAME=tbl
DQ_COL_FAILURE_COUNT=fail_n
DQ_COL_CHECK_NAME=none      # synthesize from check_type+tbl
DQ_COL_SCOPE=none           # no per-team rollup
DQ_COL_TIER=none            # use DQ_TIER1_TARGET_PCT instead

SLA 設定（オプション） — DBT_SLA_CONFIG_PATH

DBT_SLA_CONFIG_PATH に YAML ファイルを設定すると、プロジェクトで定義されたティア目標と DBT SLA を品質ツールで参照できます。スキーマ（追加のキーは無視されます）：

dbt_sla:
  test_pass_pct: 99.0          # consumed by dbt-sla-status (test pass rate threshold)
  freshness_pass_pct: 99.5     # consumed by dbt-sla-status (source freshness pass rate threshold)

tier_sla:
  1: 99.5                      # tier-1 overall_score / per-source pass-rate target
  2: 99.0
  3: 95.0

設定すると、tier_sla マップは次のように機能します。

• dq-tier-status — ティアごとの集計で、各行の overall_score を対応する目標と比較します。このファイルがない場合は、ハードコードされた {1: 99.5, 2: 99.0, 3: 95.0} が使われます。
• dq-tier-by-source — ソースごとの合格率を、そのソースのティアの目標と比較します（dbt の sources.yml にある meta.tier から解決されます）。
• dq-tier-status のティア列なしのパス（us-all プリセット／DQ_COL_TIER=none） — 単一の目標として tier_sla.1 を使います。SLA ファイルが設定されていない場合は、DQ_TIER1_TARGET_PCT 環境変数が引き続きフォールバックとして機能します。

dbt_sla ブロックは次のように機能します。

• dbt-sla-status — 最新の run_results.json からテスト合格率を計算し、sources.json から鮮度合格率を計算したうえで、各指標を dbt_sla.test_pass_pct／dbt_sla.freshness_pass_pct と比較します。各指標について passPct、target、meeting を返し、フィールドやアーティファクトが不足している場合は注意事項も返します。

ファイルの変更時刻（mtime）はキャッシュされます。ツール呼び出しの間に編集すると、その変更は自動的に反映されます。

quality_checks からのティア別集計 — dq-tier-by-source

quality_score_daily に 1 日あたり 1 行しかなく（スコープ／ティア別の内訳がない）スキーマでは、dq-tier-by-source が生の quality_checks 行からティア別の状況を再構築します。モードは 2 つあります。

mode: "source"（デフォルト）— source/dataset 列でグループ化

quality_checks の各行が ソースグループ に対するチェックを表し、dataset/source 列に dbt のソースグループ名が直接含まれている場合に使用します。

1. dbt マニフェストの sources.<source>.<table>.meta.tier から source_name -> tier のマップを作成します（各ソースグループで最初のテーブルの tier を使用します）。
2. dataset/source 列で quality_checks の行をグループ化し、日付または sinceHours の期間内におけるソースごとの合格率を計算します。
3. 各ソースの tier と目標値（SLA 設定またはデフォルト値）を参照し、tier ごとに達成状況／不足状況を報告します。

mode: "table" — table_name 列でグループ化

dataset/source 列がカテゴリ（bq／dbt／airflow）で、実際の dbt ソーステーブル識別子が <source_group>.<table> 形式で table_name／target_name 列に含まれている場合に使用します。異なるバックエンドのシグナルを統合するチェックテーブルでよく使われます。

1. マニフェストから、各ソースエントリーの source_name + name + meta.tier を使って <source_group>.<table> -> tier のマップを作成します。これにより、テーブルレベル の tier 上書きも自動的に取得できます。
2. table_name 列で quality_checks の行をグループ化します。解析可能なターゲット名を生成するカテゴリが一部のみの場合は、sourceFilter（例：sourceFilter: "bq"）で事前にフィルタリングします。
3. 各集計キーを <source_group>.<table> として解析します。. を含まない行、またはキーがマニフェストにない行は caveats[] に含まれます。

tier が設定されていない行（マニフェストに meta.tier がない行）と解析できない行は、tier を設定するか、ギャップを許容できるよう、常に caveats[] に表示されます。

対応スキーマ

• dbt マニフェストスキーマ v11／v12 — 現在の最新バージョンです。dbt 1.7 は v11 を出力し、dbt 1.8 から 1.12 はすべて v12 を出力します（スキーマはその場で後方互換性を保ちながら拡張されます）。より新しいバージョンや未知のバージョンも解析されますが、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 を参照してください。