データベース

dbt MCPの使い方：dbt CoreとClaude Codeをつなぐ設定とリモート版の選び方【2.10対応】

dbt MCPの使い方：dbt CoreとClaude Codeをつなぐ設定とリモート版の選び方【2.10対応】

dbt MCPは、dbt Labsが公式に公開しているMCP（Model Context Protocol）サーバーです。Claude CodeやCursorなどのAIエージェントから、dbtプロジェクトのモデル一覧・リネージ・テスト結果・Semantic Layerの指標を引けるようにします。本記事では、2026年11月時点の最新版dbt-mcp 2.10.1を前提に、dbt Coreだけで動かすセルフホスト版の登録手順と、dbt platformのリモート版へ接続する設定をコード付きでまとめました。後半では、AIエージェントにdbt runを任せないためのツール制限と、導入を見送る場面も書いています。

まとめ：dbt MCPはdbt Coreならセルフホスト版、指標参照はリモート版

dbt Coreのプロジェクトを手元で開発しているなら、uvx dbt-mcpで起動するセルフホスト版を選びます。必要な設定はDBT_PROJECT_DIRとDBT_PATHの2つだけで、dbt platformのアカウントは要りません。dbt platformを契約していて、指標の問い合わせやメタデータの参照が主目的なら、インストール不要のリモート版が向いています。

どちらの場合も、最初に決めるのは「AIに何をさせないか」です。dbtコマンド系のツールは、ウェアハウス上のテーブルを作り替えます。許可リストで読み取り系のツールだけを有効にし、接続先を開発用のtargetに固定してから使い始めてください。

dbt MCPサーバーの全体像：ツールセット構成とセルフホスト版・リモート版の違い

設定に入る前に、dbt MCPが何を提供していて、2つの提供形態で何が違うのかを押さえます。ここを読み違えると、設定したのにツールが出てこない状態になります。

dbt-labs公式のdbt-mcp 2.10系が提供する主なツールセットと用途

dbt MCPのソースはGitHubのdbt-labs/dbt-mcpで、Apache-2.0ライセンスのOSSとして公開されています。PyPIのdbt-mcpでは、2026年11月11日時点の最新が2.10.1（11月3日公開）で、対応するPythonは3.12以上3.15未満です。READMEのツール一覧を用途別にまとめると次のとおりです。

ツールセット 主な役割 必要なもの
dbt CLI dbtコマンドの実行 ローカルのdbt
Discovery モデル・リネージの参照 dbt platform
Semantic Layer 定義済み指標の問い合わせ dbt platform
SQL SQLの実行と自然言語変換 dbt platform
Admin API ジョブの一覧と起動 dbt platform
Codegen YAML・SQLの雛形生成 dbt-codegen
dbt LSP 列単位のリネージ dbt v2系の環境

dbt CLIツールの中身はbuild・run・test・compile・list・showなどで、Discoveryにはget_all_models・get_lineage・get_model_health、Semantic Layerにはlist_metrics・query_metricsが並びます。

dbt Coreだけの環境で使えるのは、表の1行目のdbt CLIツールと、ローカルのmanifest.jsonから依存関係を読むget_lineage_dev・get_node_details_devです。get_model_parentsやget_model_detailsは非推奨になり、get_lineageとget_node_detailsへの移行が案内されています。古いブログ記事のツール名をプロンプトに書いても、2.10系では通らない場合があるため注意が必要です。dbt v2系のエンジンについてはdbt Fusionとはで整理しています。

セルフホスト版とリモート版の違いを実行場所・dbtコマンド・API制限で比較

公式のAbout dbt MCP serverは、2つの形態を次のように分けています。

項目 セルフホスト版 リモート版
動く場所 自分のPC（uvxで起動） dbt platform（HTTP接続）
dbt run・build 使える 使えない
Codegen 使える 使えない
Semantic Layer・Discovery platform契約があれば使える 使える
API制限 公開APIごとの制限 IPあたり毎分5,000リクエスト

モデルを書いて動かす開発用途はセルフホスト版、出来上がったデータ基盤をAIから問い合わせる利用者向けはリモート版、という分担です。リモート版は全プランで提供されていますが、裏側のDiscovery APIやSemantic Layer APIはプランによって使えるものが変わる点に注意が要ります。

dbt Core環境でClaude Codeからdbt MCPを動かすセルフホスト設定手順

ここから手を動かします。dbt Coreのインストールとprofiles.ymlの作成はdbt Coreの使い方で済ませ、dbt debugが通る状態を前提にします。

uv導入済み環境でのDBT_PROJECT_DIR・DBT_PATHの絶対パス確認

dbt MCPはuvxで取得と起動をまとめて行うため、リポジトリのクローンは不要です。先にuvを入れ、2つの絶対パスを控えます。手順はRun the self-hosted dbt MCP serverに沿っています。

# macOS / Linux
which dbt        # 例: /opt/homebrew/bin/dbt
cd my_dbt_project && pwd

# Windows（コマンドプロンプト）
where dbt        # 例: C:\Python312\Scripts\dbt.exe
cd my_dbt_project && cd

DBT_PROJECT_DIRはdbt_project.ymlがあるフォルダ、DBT_PATHはdbt実行ファイルそのものを指します。WindowsではC:/Python312/Scripts/dbt.exeのようにスラッシュで書くのが公式の指定です。仮想環境にdbtを入れている場合は、その環境の中でwhere dbtを実行してください。

Claude Codeでのdbt MCP登録：コマンドと.mcp.jsonの設定

登録にはclaude mcp addを使い、設定ファイルとして.mcp.jsonを確認します。

Claude Codeでは、コマンド1行で登録できます。

claude mcp add dbt \
  -e DBT_PROJECT_DIR=/Users/yourname/projects/my_dbt_project \
  -e DBT_PATH=/opt/homebrew/bin/dbt \
  -- uvx dbt-mcp

チームで同じ設定を使うなら、リポジトリのルートに.mcp.jsonを置いてコミットする方法を公式のClaude連携ガイドが勧めています。パスは人によって違うので、値は各自の.envに逃がします。

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["--env-file", "/absolute/path/to/my_dbt_project/.env", "dbt-mcp"]
    }
  }
}

--env-fileに渡すパスは絶対パスで書きます。相対パスでは、クライアントの起動場所によって読み込めないことがあります。

Claude Desktopの設定ファイルとspawn uvx ENOENTの対処

Claude Desktopでは、Settings → Developer → Edit Configでclaude_desktop_config.jsonを開き、次を追記して再起動します。

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "C:/Users/yourname/projects/my_dbt_project",
        "DBT_PATH": "C:/Python312/Scripts/dbt.exe"
      }
    }
  }
}

つまずきやすいのは2点です。1つはspawn uvx ENOENTで、DesktopアプリがシェルのPATHを引き継がずにuvxを見つけられない状態を指します。where uvx（macOSはwhich uvx）で得たフルパスをcommandに書けば解消します。もう1つは"type": "http"の書き方で、これはClaude Code用の形式です。Desktopの設定ファイルに書くとサーバーごと読み飛ばされます。ログはWindowsなら%APPDATA%\Claude\logsにあります。

uvx dbt-mcpの単体起動とモデル一覧・リネージを尋ねる確認の手順

クライアントに登録する前に、ターミナルでuvx dbt-mcpを実行し、エラーが出ずに待機状態になるかを見ます。止めるときはCtrl+Cです。そのうえで、AIに次のように頼みます。

  1. 「このdbtプロジェクトのモデルを一覧にして」と頼み、listが呼ばれるか確かめる
  2. 「fct_ordersの上流モデルを教えて」と頼み、リネージが返るか確かめる
  3. 「stg_customersをcompileして生成SQLを見せて」と頼み、コンパイル結果を確かめる

ツールが1つも出てこない場合は、DBT_MCP_LOG_LEVEL=DEBUGを一時的に設定してログを見ます。必須の変数が欠けたツールセットはエラーにならず、黙って無効になる仕様だからです。compileはプロジェクト全体を処理するため、モデルが数百本ある場合は既定60秒のDBT_CLI_TIMEOUTを延ばしてください。

dbt platformのリモートMCPにOAuthとトークンで接続する設定

dbt platform（旧dbt Cloud）を使っているなら、ローカルにdbtを入れずにリモート版へつなげます。開発者以外のメンバーがAIから指標やリネージを調べる用途に向いています。

/api/ai/v1/mcp/のエンドポイントとOAuth接続に必要なプランと条件

エンドポイントはhttps://<ホスト名>/api/ai/v1/mcp/で、Account settings → Access URLsの「MCP Endpoint URL」からコピーできます。末尾のスラッシュは省けません。Claude Codeなら次の1行で登録し、初回接続時にブラウザでサインインと同意を済ませます。

claude mcp add --transport http dbt https://abc123.us1.dbt.com/api/ai/v1/mcp/

Connect to the remote dbt MCP serverによると、リモート版のOAuthはパブリックベータで、Starter・Enterprise・Enterprise+の各プランが対象です。abc123.us1.dbt.comのような静的サブドメインを持つアカウントでなければOAuthは使えません。クライアント側がHTTP接続のMCPサーバーに対するOAuthに対応している必要もあります。

トークン方式のヘッダー設定とexecute_sqlに個人用トークンが要る理由

OAuthが使えないクライアントやプランでは、トークンをヘッダーで渡します。Claude Codeの.mcp.jsonの例です。

{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://abc123.us1.dbt.com/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token ${DBT_TOKEN}",
        "x-dbt-prod-environment-id": "54321"
      }
    }
  }
}

必須はAuthorizationとx-dbt-prod-environment-idの2つです。IDにはブラウザのURLではなく数値だけを入れます。execute_sqlを使う場合はx-dbt-dev-environment-idとx-dbt-user-idも加え、トークンは個人用アクセストークン（PAT）にします。サービストークンではexecute_sqlが動きません。このツールはユーザーIDと開発環境IDを指定して実行する作りで、特定のユーザーに紐づくPATが前提になっています。PATを発行したくない場合は、OAuthで接続すればexecute_sqlも使えます。

Semantic Layerの指標取得条件とCopilot枠を消費するツールの区別

リモート版の価値が最も出るのは、list_metricsとquery_metricsで定義済みの指標を引く使い方です。AIがSQLを毎回自作する代わりに、MetricFlowで定義した「売上」「解約率」をそのまま問い合わせるので、人によって集計がずれることが起きにくくなります。指標の定義方法はdbt Semantic Layerの使い方にまとめています。

費用面で押さえるのは1点です。dbt Copilotのアクション枠を消費するのは、自然言語からSQLを作るtext_to_sqlだけで、ほかのツールは消費しません。枠を使い切っても止まるのはtext_to_sqlだけで、指標の問い合わせやリネージ参照は動き続けます。

AIエージェントにdbt runを任せる前に絞るツールと接続先の設計

ここからは、競合記事がほとんど触れていない安全側の設定です。dbt MCPは既定で全ツールセットが有効になり、READMEも「dbt CLIツールはデータモデルやウェアハウスのオブジェクトを変更しうる」と注意しています。

DBT_MCP_ENABLE_TOOLSで読み取り系のdbtツールだけを許可する設定

環境変数リファレンスには、無効にするものを並べるDISABLE_*と、許可するものだけを並べるDBT_MCP_ENABLE_*の2方式があります。新しいツールが版上げで増えても勝手に有効にならないので、AIに渡すなら許可リスト方式を選びます。

# /absolute/path/to/my_dbt_project/.env
DBT_PROJECT_DIR=/absolute/path/to/my_dbt_project
DBT_PATH=/opt/homebrew/bin/dbt
DBT_PROFILES_DIR=/absolute/path/to/mcp_profiles
DBT_MCP_ENABLE_TOOLS=list,parse,compile,get_lineage_dev,get_node_details_dev
DBT_CLI_TIMEOUT=180

この設定なら、AIはモデルの一覧・依存関係・生成SQLまでは調べられますが、runやbuildでテーブルを作り替えることはできません。優先順位はDBT_MCP_ENABLE_TOOLSが最上位で、DISABLE_TOOLS、ツールセット単位の指定の順に続きます。同じツールセットで2方式を混ぜると挙動が読めなくなると公式が書いているので、どちらか一方に揃えます。DBT_MCP_ENABLE_DBT_CLI=のように値が空の行も、ほかのツールセットを全部無効にしてしまうため残さないでください。

DBT_PROFILES_DIRでのMCP専用設定と本番資格情報の分離

許可リストにshowやtestを足すと、ウェアハウスへ実際にクエリが飛びます。DBT_PROFILES_DIRはMCPから使うprofiles.ymlの置き場所を変える変数で、既定は~/.dbt/です。MCP専用のディレクトリを作り、そのprofiles.ymlには開発用のtargetだけを書きます。接続ユーザーは開発スキーマの読み取りと自分用スキーマへの書き込みに権限を絞ったものにします。

普段使いの~/.dbt/profiles.ymlに本番のtargetが同居していると、AIが--target prodを付けたコマンドを組み立てたときに止める仕組みがありません。資格情報を渡さなければ、間違ったコマンドが生成されても本番には届きません。dbt platformのトークンも同じ考え方で、envに直書きするとクライアントの設定ファイルに平文で残るため、--env-fileで分けた.envを.gitignoreに入れて管理します。

dbt MCPを導入して効果が出るプロジェクトと見送る場面の判断基準

設定が済んでも、効果が出るかはプロジェクトの状態で決まります。ここでは導入の条件を言い切ります。

モデルの説明文とテストが揃っているほどAIの回答が正確になる理由

Discovery系のget_all_modelsが返すのは、モデルの名前と説明文です。説明文が空なら、AIはstg_ord_v2のような名前だけから中身を推測するしかありません。dbt MCPが返す情報の質は、YAMLに書いたdescriptionとテストの量にそのまま比例します。

導入の目安は、主要なmartsモデルの大半に説明文が付き、主キーにuniqueとnot_nullのテストがある状態です。満たしていないなら、先にdbt docsでドキュメントとリネージを整える作業と、dbt testの整備から始めるほうが、AI連携の効果は早く出ます。

dbt MCPを入れない場面：本番直結のprofilesと指標未定義の段階

次の3つのどれかに当てはまるなら、今は入れません。1つ目は、開発用と本番用のprofilesを分けられず、本番の資格情報しか手元に無い場合です。前の章の分離ができないうちにdbt CLIツールを渡すと、本番の資格情報を使う過剰なリスクを抱えてしまいます。2つ目は、利用者の目的が数字の問い合わせなのに、Semantic Layerで指標を定義していない場合です。text_to_sql任せの集計は、人によって定義がずれる問題をAIに持ち込むだけになります。

3つ目は、Python 3.12以上を入れられない社内PCで動かしたい場合です。uvがPythonを用意するとはいえ、ソフトウェアの導入制限が厳しい環境ではリモート版に寄せるほうが現実的です。dbtのデータ基盤そのものの整備や、AIエージェントとの連携設計から相談したい場合はデータ分析基盤構築・MLOps構築支援で受け付けています。

dbt MCPの導入時によくある質問と料金・対応クライアント・データの扱い

dbt MCPの導入を検討するときに出やすい質問に答えます。

dbt MCPは無料で使えますか？

セルフホスト版のdbt-mcpはApache-2.0ライセンスのOSSで、dbt Coreと組み合わせる限り費用はかかりません。リモート版はdbt platformの全プランで提供されています。ただし、Discovery APIやSemantic Layer APIを使えるかはプランによって変わるため、呼べるツールの範囲もプラン次第です。dbt Copilotのアクション枠を消費するのはtext_to_sqlだけです。プランごとの費用感はdbtとはの記事でCoreとplatformの選び方と合わせて触れています。

dbt Coreしか使っていなくてもdbt MCPは使えますか？

使えます。DBT_PROJECT_DIRとDBT_PATHを設定すれば、run・build・test・compile・list・showなどのdbt CLIツールと、ローカルのmanifest.jsonからリネージを読むツールが使えます。Semantic LayerやDiscovery API、ジョブを操作するAdmin APIはdbt platformのアカウントが前提なので、Core単体では出てきません。

dbt MCPに対応しているAIクライアントはどれですか？

公式ドキュメントには、Claude Code・Claude Desktop・Cursor・VS Codeの接続手順があり、Snowflake CortexやDatabricksとの連携ページもあります。VS Codeのmcp.jsonは"mcpServers"ではなく"servers"キーを使うなど、クライアントごとに書式が少しずつ異なるため、接続先の設定形式に合わせた記述が必要です。Claude Desktopには、設定ファイルを書かずに入れられるdbt-mcp.mcpbのバンドルも実験的に配布されています。

dbt MCPは本番データを保存したり外部に送ったりしますか？

公式は、dbt MCPサーバーが本番データやジョブの実行結果を保存しないと説明しています。ツールが呼ばれた時点で、その都度データを読みに行く仕組みです。ただし、読み取った結果はAIクライアントに渡り、利用しているAIサービスの規約に沿って処理されます。showやquery_metricsで顧客データを返させる場合は、AIサービス側のデータ取り扱い条件も確認してから許可してください。

自社でMCPサーバーを作る場合とdbt MCPはどう使い分けますか？

dbtのモデル・指標・リネージを引くだけなら、公式のdbt MCPで足ります。dbtの外にある業務システムのAPIや、社内独自の承認フローをAIから呼びたい場合は、自作のMCPサーバーを並べて登録する構成が必要です。MCPの仕組みはMCP（Model Context Protocol）とは、自作の手順はMCPサーバーの作り方で解説しています。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

この記事に関連するサービス

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.09　テックブログ エディオン不正アクセス第2報：カード番号の対象確認とログ・決済画面の改ざん対策
  2. 2026.11.09　テックブログ LANSCOPE不正アクセス第2報：製品への影響と偽連絡の確認、停止中のライセンス認証の窓口
  3. 2026.11.10　テックブログ Claude Fable 5.2とは：料金・破壊的変更4点とFable 5.1からの移行手順【2026年11月】
  4. 2026.11.10　テックブログ ニトリの情報漏洩：最大3,762万件の対象確認となりすまし連絡の見分け方
  5. 2026.11.09　テックブログ ステップゴルフ不正アクセス：口座情報の対象確認と偽連絡・引き落としの注意点

RELATED POSTS 関連記事

一覧へ戻る

目次