configuring-dbt-mcp-server

dbt MCP サーバーを設定する

概要

dbt MCP サーバーは、AI ツールを dbt の CLI、Semantic Layer、Discovery API、Admin API に接続します。このスキルでは、ユースケースに合った設定でセットアップする方法を説明します。

判断の流れ

flowchart TB
    start([User wants dbt MCP]) --> q1{Local or Remote?}
    q1 -->|dev workflows,<br>CLI access needed| local[Local Server<br>uvx dbt-mcp]
    q1 -->|consumption only,<br>no local install| remote[Remote Server<br>HTTP endpoint]
    local --> q2{Which client?}
    remote --> q2
    q2 --> claude_desktop[Claude Desktop]
    q2 --> claude_code[Claude Code]
    q2 --> cursor[Cursor]
    q2 --> vscode[VS Code]
    claude_desktop --> config[Generate config<br>+ test setup]
    claude_code --> config
    cursor --> config
    vscode --> config

確認する質問

1. サーバーの種類

質問:「ローカルとリモートのどちらの dbt MCP サーバーを使用しますか？」

ローカルサーバー	リモートサーバー
uvx を使ってお使いのマシンで実行します	HTTP 経由で dbt platform に接続します
開発（モデル、テスト、ドキュメントの作成）に必要ですが、利用（メトリクスのクエリ、メタデータの探索）のために dbt platform に接続することもできます	利用（メトリクスのクエリ、メタデータの探索）に最適です
dbt CLI コマンド（run、build、test、show）に対応しています	CLI コマンド（run、build、test）には対応していません
dbt platform アカウントなしで動作しますが、開発（モデル、テスト、ドキュメントの作成）のために dbt platform に接続することもできます	dbt platform アカウントが必要です
クレジットを消費しません	dbt Copilot クレジットを消費します

2. MCP クライアント

質問:「どの MCP クライアントを使用していますか？」

• Claude Desktop
• Claude Code（CLI）
• Cursor
• VS Code

3. ユースケース（ローカルサーバーのみ）

質問:「どのような用途で使用しますか？」

CLI のみ	プラットフォームのみ	プラットフォーム + CLI
dbt Core/Fusion のユーザー	ローカルプロジェクトなしで dbt Cloud を使用	両方にフルアクセス
プラットフォームアカウントは不要	OAuth またはトークン認証	パスと認証情報が必要

4. 有効にするツール

質問:「どのツールを有効にしますか？」（デフォルトを表示）

ツールのカテゴリ	デフォルト	環境変数
dbt CLI（run、build、test、compile）	有効	DISABLE_DBT_CLI=true で無効化
Semantic Layer（メトリクス、ディメンション）	有効	DISABLE_SEMANTIC_LAYER=true で無効化
Discovery API（モデル、リネージ）	有効	DISABLE_DISCOVERY=true で無効化
Admin API（ジョブ、実行）	有効	DISABLE_ADMIN_API=true で無効化
SQL（text_to_sql、execute_sql）	無効	DISABLE_SQL=false で有効化
Codegen（モデル／ソースの生成）	無効	DISABLE_DBT_CODEGEN=false で有効化

前提条件

ローカルサーバー

1. uv をインストールします：https://docs.astral.sh/uv/getting-started/installation/
2. dbt プロジェクトを用意します（CLI コマンド用）
3. パスを確認します：
   • DBT_PROJECT_DIR：dbt_project.yml を含むフォルダー
     • macOS/Linux：プロジェクトフォルダーで pwd
     • Windows：スラッシュを使用したフルパス（例：C:/Users/name/project）
   • DBT_PATH：dbt 実行ファイルへのパス
     • macOS/Linux：which dbt
     • Windows：where dbt

リモートサーバー

1. AI 機能が有効になっている dbt Cloud アカウント
2. 本番環境 ID（Orchestration ページで確認）
3. 個人アクセストークンまたはサービス トークン

トークンと ID の取得方法について詳しくは、認証情報の確認方法をご覧ください。

認証情報のセキュリティ

• バージョン管理にコミットする可能性のある設定ファイルでは、トークンの値を直接記述するのではなく、環境変数への参照（例：${DBT_TOKEN}）を必ず使用してください
• ターミナルの出力にトークンの値を記録、表示、または出力しないでください
• .env ファイルを使用する場合は、誤ってコミットされないよう、必ず .gitignore に追加してください
• トークンは定期的にローテーションし、必要最小限の権限セットを使用するようユーザーに推奨してください

設定テンプレート

ローカルサーバー — CLI のみ

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

ローカルサーバー — プラットフォーム + CLI（OAuth）

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "https://your-subdomain.us1.dbt.com",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

ローカルサーバー — プラットフォーム + CLI（トークン認証）

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "${DBT_TOKEN}",
        "DBT_ACCOUNT_ID": "${DBT_ACCOUNT_ID}",
        "DBT_PROD_ENV_ID": "${DBT_PROD_ENV_ID}",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

ローカルサーバー — .env ファイルを使用

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

.env ファイルの内容：

DBT_HOST=cloud.getdbt.com
DBT_TOKEN=<set-via-env-or-secret-manager>
DBT_ACCOUNT_ID=<your-account-id>
DBT_PROD_ENV_ID=<your-prod-env-id>
DBT_DEV_ENV_ID=<your-dev-env-id>
DBT_USER_ID=<your-user-id>
DBT_PROJECT_DIR=/path/to/project
DBT_PATH=/path/to/dbt

リモートサーバー

{
  "mcpServers": {
    "dbt": {
      "url": "https://cloud.getdbt.com/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token ${DBT_TOKEN}",
        "x-dbt-prod-environment-id": "${DBT_PROD_ENV_ID}"
      }
    }
  }
}

SQL/Fusion ツール用の追加ヘッダー：

{
  "headers": {
    "Authorization": "Token ${DBT_TOKEN}",
    "x-dbt-prod-environment-id": "${DBT_PROD_ENV_ID}",
    "x-dbt-dev-environment-id": "${DBT_DEV_ENV_ID}",
    "x-dbt-user-id": "${DBT_USER_ID}"
  }
}

クライアント別のセットアップ

Claude Desktop

1. システムメニューバーの Claude メニュー をクリックします（アプリ内ではありません）
2. Settings... を選択します
3. Developer タブに移動します
4. Edit Config をクリックします
5. JSON 設定を追加します
6. 保存して Claude Desktop を再起動します
7. 確認： 入力ボックスの右下に MCP サーバーのインジケーターが表示されていることを確認します

設定ファイルの場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

Claude Code（CLI）

次を実行します：

claude mcp add dbt -s user -- uvx dbt-mcp

これにより、ユーザースコープ／設定（このシステムでは ~/.claude.json）にサーバーが追加されます。

プロジェクト固有のセットアップを行うには、次を実行します：

claude mcp add dbt -s project -- uvx dbt-mcp

これにより、プロジェクトのルートにある .mcp.json にサーバーが追加されます。

または、以下の手動設定を使用できます。

手動設定： ~/.claude.json（ユーザースコープ）を編集するか、プロジェクトのルートに .mcp.json（プロジェクトスコープ）を作成します。

• ~/.claude.json：すべてのプロジェクトに適用されます
• .mcp.json：プロジェクト固有の設定です。チームで共有するためにバージョン管理にコミットできます。トークン認証を使用する場合は、環境変数への参照を使用してください。トークンを直接記述した設定は決してコミットしないでください。

プロジェクト固有の dbt セットアップでは、チームで同じ設定を共有できるよう .mcp.json を使用してください。

設定ファイルを作成したら、mcpServers キーの下に JSON 設定を追加してください。

Cursor

1. Cursor メニュー → Settings → Cursor Settings → MCP を開きます
2. JSON 設定を追加します
3. パスと認証情報を更新します
4. 保存します

VS Code

1. コマンドパレット（Cmd/Ctrl + Shift + P）を開きます
2. 「MCP: Open User Configuration」（プロジェクト固有の場合は Workspace）を実行します
3. JSON 設定を追加します（注：VS Code では mcpServers ではなく servers を使用します）。

{
  "servers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

4. Settings → Features → Chat を開き、MCP を有効にします
5. 確認： コマンドパレットから 「MCP: List Servers」 を実行します

WSL ユーザー： ローカルのユーザー設定ではなく、リモート設定で構成してください。

• コマンドパレットから 「Preferences: Open Remote Settings」 を実行します
• Linux のフルパスを使用します（例：Windows パスではなく /home/user/project）

確認手順

ローカルサーバー設定のテスト

推奨：.env ファイルを使用

1. プロジェクトのルートディレクトリに .env ファイルを作成し、CLI ツールに必要最小限の環境変数を追加します。

DBT_PROJECT_DIR=/path/to/project
DBT_PATH=/path/to/dbt

2. サーバーをテストします。

uvx --env-file .env dbt-mcp

代替方法：環境変数

# Temporary test (variables only last for this session)
export DBT_PROJECT_DIR=/path/to/project
export DBT_PATH=/path/to/dbt
uvx dbt-mcp

エラーがなければ、設定は成功です。

クライアントでの確認

セットアップ後、AI に次のように尋ねます。

• 「どの dbt ツールを利用できますか？」
• 「自分の dbt メトリクスを一覧表示して」（Semantic Layer が有効な場合）
• 「自分の dbt モデルを表示して」（Discovery が有効な場合）

一般的な問題と解決方法については、トラブルシューティングを参照してください。

サポートされているすべての変数については、環境変数リファレンスを参照してください。