dbt MCP Server (Official)

dbt MCP Server (Official) とは？

dbt MCP サーバーは、dbt Labs 公式の Model Context Protocol サーバーです。dbt Core、dbt Fusion、dbt platform にまたがって、リネージ、モデルのメタデータ、Semantic Layer のメトリクス、dbt CLI コマンド、ジョブ管理といった dbt プロジェクトのコンテキストとツールを AI エージェントに提供します。

提供形態は 2 つあります。セルフホスト版は uvx dbt-mcp で自分のマシン上で動き、モデル、テスト、ドキュメントの作成といった開発作業に向いています。リモート版は dbt が https://YOUR_DBT_HOST_URL/api/ai/v1/mcp でホストしており、インストール不要で、メトリクスの照会、メタデータの探索、リネージの確認といった利用側の作業に向いています。

dbt MCP Server (Official) の使い方

セルフホストの前提条件： uv をインストールし、CLI ツールを使う場合はローカルの dbt プロジェクトを用意します。dbt-mcp リポジトリをクローンする必要はありません。dbt platform の機能を使うには、アクセス URL（例：abc123.us1.dbt.com）と、OAuth またはトークンが必要です。

主な環境変数：CLI 用には DBT_PROJECT_DIR（dbt_project.yml があるフォルダー）と DBT_PATH（dbt 実行ファイルのフルパス。which dbt で確認）、platform 用には DBT_HOST、DBT_TOKEN、DBT_PROD_ENV_ID、さらに Admin API や PAT 認証では DBT_ACCOUNT_ID を使います。

Claude Desktop

最も手早いのは dbt-mcp.mcpb バンドルです。GitHub の最新リリースからダウンロードし、ダブルクリックして Claude Desktop で開き、dbt platform のホストを入力してサーバーを有効にします。手動で設定する場合は Settings > Developer > Edit Config を開いて次を追加します。

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/your/dbt/executable",
        "DBT_HOST": "YOUR-ACCESS-URL"
      }
    }
  }
}

CLI だけを使う場合は DBT_HOST を、platform だけを使う場合は 2 つの CLI 変数を省略します。リモートサーバーを使うには、Chat > Customize > Connectors で MCP URL を指定してカスタムコネクタを追加し、OAuth フローを完了します。

Claude Code

リモートサーバーに接続します。

claude mcp add --transport http dbt https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/

トークン認証を使う場合は、プロジェクトの .mcp.json にヘッダーを指定します。

{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token YOUR_DBT_ACCESS_TOKEN",
        "x-dbt-prod-environment-id": "DBT_PROD_ENV_ID"
      }
    }
  }
}

Cursor と VS Code

dbt はどちらにも連携ガイドを用意しています。上記のセルフホスト用 uvx dbt-mcp ブロックは、Cursor の mcp.json の mcpServers エントリとしてそのまま使えます。VS Code では、同じコマンドと環境変数を .vscode/mcp.json の servers の下に記述します。

dbt MCP Server (Official) の主な機能

• dbt Labs による公式のオープンソースサーバー（Apache-2.0）
• dbt Core、dbt Fusion、dbt platform に対応
• uvx dbt-mcp でのセルフホスト、または OAuth やトークンヘッダーを使った HTTP でのリモート接続
• Discovery API によるリネージとモデルの健全性。カラムレベルのリネージにも対応
• Semantic Layer でのメトリクス、ディメンション、保存済みクエリの照会
• build、run、test、compile などの dbt CLI コマンド（セルフホストのみ）
• ジョブ実行の一覧・トリガー・キャンセル・リトライを行う Admin API ツール
• DISABLE_* 変数や x-dbt-disable-tools ヘッダーによるきめ細かな制御

dbt MCP Server (Official) のツール

ツールはツールセットごとにまとめられており、個別にオン・オフできます。

• Discovery： get_all_models、get_lineage、get_node_details、get_model_health、get_all_sources でプロジェクトのメタデータを探索します。いくつかの古い詳細取得ツールは非推奨となり、get_node_details に統合されています。
• Semantic Layer： list_metrics、get_dimensions、query_metrics、get_metrics_compiled_sql。
• SQL： execute_sql と text_to_sql。セルフホストではデフォルトで無効です。execute_sql には個人用アクセストークンが必要で、text_to_sql は dbt Copilot のアクションを消費する唯一のツールです。
• dbt CLI： build、compile、run、test、show、parse、list、docs。モデルやウェアハウスのオブジェクトを変更する可能性があります。
• Admin API： list_jobs、trigger_job_run、get_job_run_error、retry_job_run、cancel_job_run。
• Codegen： generate_source、generate_model_yaml、generate_staging_model（デフォルトでは無効。dbt-codegen パッケージが必要）。
• dbt LSP とドキュメント： get_column_lineage、fusion.compile_sql、docs.getdbt.com を検索する search_product_docs。

dbt MCP Server (Official) のユースケース

• 影響分析：「What models are downstream of stg_orders, and which dashboards depend on them?」
• メトリクスの質問：「What is the total revenue for the last 30 days?」に Semantic Layer 経由で回答。
• ジョブのデバッグ：「Why did last night's production job fail? Show the error and retry it.」
• 開発：「Generate a staging model and YAML for the raw.payments source, then run its tests.」
• モデルの健全性チェック：「Which mart models have failing tests or stale sources?」
• ドキュメント検索：「Search the dbt docs for how incremental models handle schema changes.」

dbt MCP Server (Official) と代替ツールの比較

主な選択肢は 2 つの公式版のどちらを使うかです。セルフホスト版の dbt MCP サーバーは、開発向けに CLI コマンド、コード生成、ローカル manifest のツールを提供します。リモート版はインストール不要で Semantic Layer、SQL、Discovery、ドキュメントのツールをカバーしますが、dbt CLI コマンドは実行しません。dbt のコンテキストなしでウェアハウスに直接クエリするだけなら、Postgres MCP のようなデータベースサーバーのほうがシンプルですが、モデル、リネージ、メトリクスについての知識はありません。

dbt MCP Server (Official) のトラブルシューティング

• spawn uvx ENOENT や「Could not connect to MCP server」： クライアントが uvx を見つけられていません。which uvx（macOS/Linux）または where uvx（Windows）を実行し、フルパスを command に指定します。
• OAuth ログインが始まらない： 残ったロックファイルが妨げている可能性があります。クライアントを閉じて rm -f ~/.dbt/mcp.yml ~/.dbt/mcp.lock を実行し、再起動します。アカウント管理者が dbt Wizard 機能を有効にしているかも確認してください。
• サービストークンで execute_sql が失敗する： 個人用アクセストークン、またはリモートサーバーでの OAuth が必要です。
• ID が拒否される： ダッシュボードの URL ではなく、DBT_PROD_ENV_ID=54321 のような数値を使います。
• SQL や codegen のツールが見当たらない： デフォルトで無効になっています。DISABLE_SQL=false または DISABLE_DBT_CODEGEN=false を設定します。