dbt MCPサーバーの使い方 — Claude CodeでDAG実行とリネージ確認
dbt MCPサーバーをClaude Codeに接続し、build・compile・runでモデルを実行し、manifest.jsonからリネージを取得する手順をまとめます。
MCPはAIエージェントと外部ツールをつなぐ標準プロトコルで、仕組み自体はMCPとはにまとめています。dbt MCPサーバー(dbt-mcp)は、dbtのモデル実行・ドキュメント生成・リネージ取得をClaudeから直接呼び出せるようにするdbt Labs公式のMCPサーバーです。uvx dbt-mcpだけでインストールが完了し、Claude Codeに登録すればdbt buildやdbt compileをチャットの自然文から実行できます。この記事では、自分のPCにあるdbtプロジェクトを対象にしたself-hosted構成を軸に、DAG実行とリネージ確認までの手順をまとめます。メトリクスへの自然言語問い合わせは扱う範囲が異なるため、dbt Semantic Layerの使い方で別記事にしています。
dbt MCPサーバーとは — self-hostedとremoteの違い
dbt MCPサーバーには2つの提供形態があります。self-hostedは手元のマシンで動かす方式で、uvx経由でdbt-mcpをインストールし、dbt runやdbt buildのようなCLIコマンドをそのままツール化します。remoteはdbt platformがホストするHTTPエンドポイントに接続する方式で、インストール不要な代わりにCLIコマンドは使えません。
| 項目 | self-hosted | remote |
|---|---|---|
| CLIコマンド(build/compile/run等) | self-hosted対応 | remote非対応 |
| Semantic Layer / SQL / Discovery / Admin API | self-hosted対応(dbt platformアカウントが必要) | remote対応(プランにより機能差) |
| インストール | self-hosteduvが必要 | remote不要(HTTP接続のみ) |
| 向く用途 | self-hostedモデル開発・DAG実行・ローカルリネージ | remoteメトリクス照会中心のデータ消費 |
モデルを実際に実行したりmanifest.jsonからリネージを取り出したりする用途はself-hostedでしか対応していません。この記事が扱うのはself-hosted構成です。dbt platformアカウントを持たなくても、dbt CoreとdbtプロジェクトさえあればCLIツール群は動きます。
Claude Codeへの接続手順
まずuvをインストールします。dbt-mcpのリポジトリをクローンする必要はなく、uvx dbt-mcpが実行時に自動でパッケージを取得します。
接続に必要な値は2つです。
# DBT_PATHを調べる(dbt実行ファイルの場所)
which dbt
# DBT_PROJECT_DIRを調べる(dbt_project.ymlがあるフォルダ)
cd /path/to/your/dbt/project && pwd2つの値が揃ったら、Claude Codeのclaude mcp addで登録します。
claude mcp add dbt \
-e DBT_PROJECT_DIR=/path/to/your/dbt/project \
-e DBT_PATH=/path/to/your/dbt/executable \
-- uvx dbt-mcpclaude mcp listでdbtが✔ Connectedになれば準備は完了です。dbt platformアカウントを持っていて、Semantic LayerやDiscovery APIも同時に使いたい場合は、DBT_HOST・DBT_TOKEN・DBT_PROD_ENV_IDを追加で渡せば、CLIツールとdbt platformツールが1つのサーバーに同居します。dbt platformアカウントを使わずCLIだけに絞る場合は、この3つを渡さなければCLIツールだけが自動的に有効になります。
モデルをDAG順に実行する — build / compile / runの使い分け
dbt CLIカテゴリーのツールは、dbtコマンドをそのままMCPツールとして公開したものです。
| ツール | 相当するdbtコマンド | できること |
|---|---|---|
build | 相当するdbtコマンドdbt build | できることモデル・テスト・スナップショット・シードをDAG順に一括実行 |
run | 相当するdbtコマンドdbt run | できることモデルをマテリアライズ(実体化)する |
compile | 相当するdbtコマンドdbt compile | できることモデル・テスト・分析からSQLを生成。Jinjaロジックの検証に便利 |
test | 相当するdbtコマンドdbt test | できることデータとモデルの整合性テストを実行 |
parse | 相当するdbtコマンドdbt parse | できることプロジェクトファイルの構文を検証 |
show | 相当するdbtコマンドdbt show | できることSQLをウェアハウスに対して実行し結果を返す |
list | 相当するdbtコマンドdbt list | できることセレクター指定でプロジェクト内のリソースを一覧表示 |
clone | 相当するdbtコマンドdbt clone | できること選択したノードを指定のstateからターゲットスキーマへ複製 |
docs | 相当するdbtコマンドdbt docs generate | できることプロジェクトのドキュメントを生成 |
インストールが終われば、あとは自然文で頼むだけです。
stg_ordersモデルとその下流だけをbuildしてこの聞き方ではbuildツールがdbtのセレクター構文に変換されて呼ばれ、対象モデルとその依存関係だけがDAG順に実行されます。Jinjaマクロが複雑なモデルで生成SQLだけを先に見たいときは、compileを使う聞き方に切り替えます。
fct_revenueモデルのコンパイル後SQLを見せてbuildは実行までまとめて行う一方、compileはSQLを生成するだけでウェアハウスへの実行は行いません。本番相当のデータに影響を与えたくないレビュー段階ではcompile、実際にモデルを更新したい段階ではbuildかrunと使い分けます。
manifest.jsonからリネージを確認する
dbt MCPサーバーには、実は2系統のリネージ取得手段があります。
| ツール | 取得元 | 前提条件 |
|---|---|---|
get_lineage_dev | 取得元ローカルのmanifest.json | 前提条件dbt platformアカウント不要。dbt compile等で生成済みのmanifestが必要 |
get_lineage(Discovery API) | 取得元dbt platformのメタデータ | 前提条件dbt platformアカウントが必要 |
get_lineage_devは手元のプロジェクトをcompileかparseした際に生成されるmanifest.jsonを直接読み込むため、dbt platformにアカウントがなくても使えます。祖先(upstream)・子孫(downstream)の両方向を、深さとノード種別でフィルタしながら取得できます。同じくローカルmanifestベースのget_node_details_devと組み合わせれば、モデル・ソース・テストなど任意のリソースの詳細をdbt platformなしで確認できます。
fct_revenueモデルの依存元(upstream)を3階層分たどってdbt platformアカウントを持っている場合は、Discovery API経由のget_lineageでより広いメタデータ(実行履歴やテスト結果と紐づいたリネージ)を取得できます。ローカル開発中は_dev系、CI後の実行状況まで含めて確認したいときはDiscovery API系、という住み分けです。
カラム単位のリネージも追える(dbt LSP)
モデル単位のリネージだけでなく、特定のカラムがどのモデルのどのカラムに由来するかを追いたい場面もあります。dbt MCPサーバーはFusionエンジンを使ったdbt LSPカテゴリーで、この列単位のリネージにも対応しています。
| ツール | 取得元 | 前提条件 |
|---|---|---|
get_column_lineage | 取得元ローカル | 前提条件dbt Labs VSCEのdbt-lspが必要 |
fusion.get_column_lineage | 取得元dbt platform | 前提条件dbt platformアカウントが必要 |
fusion.compile_sql | 取得元dbt platform | 前提条件プロジェクトコンテキストでのSQLコンパイル |
fct_revenueのamountカラムは、どのソーステーブルのどのカラムに由来する?モデル単位のget_lineage_devでは「どのモデルに依存しているか」までしか分かりませんが、get_column_lineageまで使えば「そのモデルのどのカラムが最終的な数値に効いているか」を1段掘り下げて確認できます。データの数値がおかしいときに、モデル全体ではなく特定カラムの計算過程だけを遡って調べたいケースで役立ちます。
使えるツールを絞り込む — DISABLE_とENABLE_
dbt MCPサーバーは既定でほぼ全ツールセットが有効になっています。ツールセット単位で無効化する変数と、逆に許可リストだけを有効にする変数の2モードがあり、両方を同じツールセットに混在させると挙動が不安定になるため、どちらか一方に統一します。
| 変数 | 既定値 | 対象 |
|---|---|---|
DISABLE_DBT_CLI | 既定値false | 対象dbt CLIツール(build/run/compile等) |
DISABLE_SEMANTIC_LAYER | 既定値false | 対象Semantic Layerツール |
DISABLE_DISCOVERY | 既定値false | 対象Discovery APIツール(get_lineage等) |
DISABLE_ADMIN_API | 既定値false | 対象Admin APIツール(ジョブ管理) |
DISABLE_SQL | 既定値true | 対象SQL実行ツール。既定で無効 |
DISABLE_DBT_CODEGEN | 既定値true | 対象コード生成ツール。既定で無効 |
CI用のジョブ実行やAdmin APIのような読み書きの重いツールを封じたいだけなら、DISABLE_ADMIN_API=trueのように該当変数だけをenv経由で渡します。特定のツール名だけを個別に外したい場合はDISABLE_TOOLSにカンマ区切りで指定します。
逆に、限られたツールセットだけを使わせたい場合はenableモードに切り替えます。DBT_MCP_ENABLE_*のいずれかを1つでも設定すると、明示的に有効化したツールセットだけが動く許可リスト方式に切り替わります。
| 変数 | 用途 |
|---|---|
DBT_MCP_ENABLE_DBT_CLI | 用途dbt CLIツールだけを有効化 |
DBT_MCP_ENABLE_DISCOVERY | 用途Discovery APIツールだけを有効化 |
DBT_MCP_ENABLE_LSP | 用途dbt LSP/Fusionツール(カラム単位のリネージ含む)だけを有効化 |
DBT_MCP_ENABLE_TOOLS | 用途カンマ区切りで指定した個別ツール名だけを有効化 |
読み取り専用のリネージ確認だけをレビュー担当者に開放したい場合は、DBT_MCP_ENABLE_DISCOVERY=trueとDBT_MCP_ENABLE_LSP=trueだけを設定すれば、buildのような書き込みを伴うCLIツールは一切見えない状態にできます。空文字のDBT_MCP_ENABLE_*=をうっかり残すとenableモードそのものが有効化され、他のすべてのツールセットが無効になる点には注意します。
サーバー全体でツールセットを絞ったうえで、さらにツール単位の実行確認を挟みたい場合はClaude Code側のpermissionsを組み合わせます。ルールはmcp__dbt__<ツール名>の形式で書け、書き方の全般はClaude Code MCP設定ガイドにまとめています。
dbt Semantic Layerとの役割分担
このMCPサーバーにはSemantic Layer関連のツール(list_metricsやquery_metricsなど)も含まれますが、これらはdbt platformアカウントが前提で、モデル層で定義したメトリクスに自然言語で問い合わせる用途に特化しています。DAG実行やリネージ確認とは目的が異なるため、Semantic Layer側のツールと設定は冒頭で触れた別記事で扱っています。同じMCPサーバーの中に両方のツールセットが同居しているので、DBT_HOST等を設定すれば1つの接続で両方を切り替えて使えます。
よくあるつまずき
spawn uvx ENOENTのようなエラーが出る: Claude Codeがuvxの実行パスを見つけられていない。which uvxで得たフルパスをclaude mcp addのコマンドに直接指定するget_lineage_devが空を返す:manifest.jsonが生成されていないか古い。compileかparseツールを一度呼んでmanifestを最新化してから再試行する- CLIツールが動かずDiscoveryツールだけ動く:
DBT_PROJECT_DIRかDBT_PATHが未設定、またはDISABLE_DBT_CLI=trueになっている。両変数を渡しているか確認する DISABLE_*とDBT_MCP_ENABLE_*を両方設定してしまう: 同じツールセットに両モードを混在させると想定外の挙動になる。無効化したいだけならdisableモード、限定した数個だけ使いたいならenableモードのどちらかに統一する- 大規模プロジェクトで
compileがタイムアウトする:DBT_CLI_TIMEOUTの既定値は60秒で、モデル数が多いプロジェクトのcompileはプロジェクト全体を対象にするため足りないことがある。この変数を大きい値に設定して再試行する
よくある質問
dbt platformアカウントがなくても使えますか
使えます。DBT_PROJECT_DIRとDBT_PATHだけを渡せば、dbt CLIツール(build/compile/run/test等)と、ローカルmanifest.jsonベースのget_lineage_dev・get_node_details_devが動きます。Semantic Layer・Discovery API(非dev系)・Admin API・SQL実行はdbt platformアカウントが必要です。
dbt Coreとdbt Fusionのどちらでも使えますか
使えます。dbt MCPサーバーはdbt Core・dbt Fusion・dbt platformのいずれの実行環境にも対応しており、DBT_PATHが指す実行ファイルに応じて動きます。
Claude Desktopでも同じ設定が使えますか
使えます。Claude Desktopはclaude_desktop_config.jsonのmcpServersにJSONで同じDBT_PROJECT_DIR・DBT_PATHを書き込む形になります。設定ファイルの場所はmacOSが~/Library/Application Support/Claude/claude_desktop_config.json、Windowsが%APPDATA%\Claude\claude_desktop_config.jsonです。
execute_sqlツールも使えますか
DISABLE_SQLが既定でtrueのため無効です。有効にするにはDISABLE_SQL=falseを明示的に渡します。SQL実行はモデル・ソースへの読み書きに直結するため、有効化する場合は接続先を検証環境に絞るなど、実行範囲を限定してから使うのが安全です。
まとめ
dbt MCPサーバーは、DBT_PROJECT_DIRとDBT_PATHさえ渡せばdbt platformアカウントなしでもCLI操作をClaudeから呼び出せます。buildで実行までまとめて行うかcompileでSQL生成だけに留めるかを使い分け、リネージはdbt platformの有無でget_lineage_dev(ローカルmanifest)とget_lineage(Discovery API)を切り替えます。dbt CLIツールは書き込みを伴うため、DISABLE_*とenableモードのどちらか一方に統一してツールセットを絞り込んでおくと、意図しないモデル変更を避けやすくなります。メトリクスへの自然言語問い合わせを主目的にする場合は、同じMCPサーバーが提供するSemantic Layer側のツールを使います。