---
title: "dbt MCPの使い方：dbt CoreとClaude Codeをつなぐ設定とリモート版の選び方【2.10対応】"
url: "https://www.issoh.co.jp/tech/details/19615/"
published: 2026-11-11
updated: 2026-11-11
categories: ["データベース"]
publisher: "株式会社一創"
---

# 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](https://github.com/dbt-labs/dbt-mcp)で、Apache-2.0ライセンスのOSSとして公開されています。[PyPIのdbt-mcp](https://pypi.org/project/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とは](https://www.issoh.co.jp/tech/details/19593/)で整理しています。

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

[公式のAbout dbt MCP server](https://docs.getdbt.com/docs/dbt-ai/about-mcp)は、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の使い方](https://www.issoh.co.jp/tech/details/19592/)で済ませ、`dbt debug`が通る状態を前提にします。

### uv導入済み環境でのDBT\_PROJECT\_DIR・DBT\_PATHの絶対パス確認

dbt MCPは`uvx`で取得と起動をまとめて行うため、リポジトリのクローンは不要です。先にuvを入れ、2つの絶対パスを控えます。手順は[Run the self-hosted dbt MCP server](https://docs.getdbt.com/docs/dbt-ai/mcp-quickstart-cli)に沿っています。

```
# 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連携ガイド](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-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](https://docs.getdbt.com/docs/dbt-ai/mcp-quickstart-remote)によると、リモート版の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の使い方](https://www.issoh.co.jp/tech/details/19595/)にまとめています。

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

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

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

### DBT\_MCP\_ENABLE\_TOOLSで読み取り系のdbtツールだけを許可する設定

[環境変数リファレンス](https://docs.getdbt.com/docs/dbt-ai/mcp-environment-variables)には、無効にするものを並べる`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でドキュメントとリネージを整える作業](https://www.issoh.co.jp/tech/details/19599/)と、[dbt testの整備](https://www.issoh.co.jp/tech/details/19611/)から始めるほうが、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構築支援](https://www.issoh.co.jp/service/ai/data-platform/)で受け付けています。

## 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とは](https://www.issoh.co.jp/column/details/16548/)の記事で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）とは](https://www.issoh.co.jp/tech/details/5736/)、自作の手順は[MCPサーバーの作り方](https://www.issoh.co.jp/tech/details/15365/)で解説しています。

## 関連記事

- [dbtとは？ELTのTを担う仕組みとdbt Core・Cloudの選び方【2026年版】](https://www.issoh.co.jp/column/details/16548/)：dbtの仕組みと採用判断
- [dbt Coreの使い方：インストールからprofiles.yml・dbt build・CIまでの手順【1.12対応】](https://www.issoh.co.jp/tech/details/19592/)：dbt MCPを動かす前の環境構築
- [dbt Semantic Layerの使い方：設定からJDBC・GraphQL・Python SDKで指標を引くまで【2026年版】](https://www.issoh.co.jp/tech/details/19595/)：query\_metricsで引く指標の定義
- [dbt docsの使い方：generate・serveでリネージを作り社内に公開する手順【v2対応】](https://www.issoh.co.jp/tech/details/19599/)：AIに渡す説明文とリネージの整備
- [MCP（Model Context Protocol）とは？仕組み・APIとの違い・MCPサーバーの作り方](https://www.issoh.co.jp/tech/details/5736/)：MCPそのものの仕組み

---

出典: [dbt MCPの使い方：dbt CoreとClaude Codeをつなぐ設定とリモート版の選び方【2.10対応】](<https://www.issoh.co.jp/tech/details/19615/>)（株式会社一創）