DBT CLI MCP Server

DBT CLI MCP サーバー

dbt CLI ツールをラップし、AI コーディングエージェントが標準化された MCP ツールを通じて dbt プロジェクトを操作できるようにする、Model Context Protocol（MCP）サーバーです。

機能

• MCP ツールを通じて dbt コマンドを実行
• 主要な dbt 操作（run、test、compile など）をサポート
• 直接操作できるコマンドラインインターフェース
• dbt プロジェクトの環境変数管理
• dbt 実行ファイルのパスを設定可能
• profiles.yml の場所を柔軟に設定可能

インストール

前提条件

• Python 3.10 以降
• Python 環境の管理に使用する uv ツール
• dbt CLI がインストールされていること

セットアップ

# Clone the repository with submodules
git clone --recurse-submodules https://github.com/yourusername/dbt-cli-mcp.git
cd dbt-cli-mcp

# If you already cloned without --recurse-submodules, initialize the submodule
# git submodule update --init

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# For development, install development dependencies
uv pip install -e ".[dev]"

使用方法

コマンドラインインターフェース

このパッケージには、dbt を直接操作するためのコマンドラインインターフェースが用意されています。

# Run dbt models
dbt-mcp run --models customers --project-dir /path/to/project

# Run dbt models with a custom profiles directory
dbt-mcp run --models customers --project-dir /path/to/project --profiles-dir /path/to/profiles

# List dbt resources
dbt-mcp ls --resource-type model --output-format json

# Run dbt tests
dbt-mcp test --project-dir /path/to/project

# Get help
dbt-mcp --help
dbt-mcp run --help

モジュールを直接使用することもできます。

python -m src.cli run --models customers --project-dir /path/to/project

コマンドラインオプション

• --dbt-path：dbt 実行ファイルのパス（デフォルト：「dbt」）
• --env-file：環境ファイルのパス（デフォルト：「.env」）
• --log-level：ログレベル（デフォルト：「INFO」）
• --profiles-dir：profiles.yml ファイルを含むディレクトリのパス（指定しない場合は project-dir がデフォルトになります）

環境変数

環境変数を使用してサーバーを設定することもできます。

• DBT_PATH：dbt 実行ファイルのパス
• ENV_FILE：環境ファイルのパス
• LOG_LEVEL：ログレベル
• DBT_PROFILES_DIR：profiles.yml ファイルを含むディレクトリのパス

MCP クライアントでの使用

Claude for Desktop などの MCP クライアントでサーバーを使用するには、クライアントの設定に追加します。

{
  "mcpServers": {
    "dbt": {
      "command": "uv",
      "args": ["--directory", "/path/to/dbt-cli-mcp", "run", "src/server.py"],
      "env": {
        "DBT_PATH": "/absolute/path/to/dbt",
        "ENV_FILE": ".env"
        // You can also set DBT_PROFILES_DIR here for a server-wide default
      }
    }
  }
}

⚠️ 重要：プロジェクトの絶対パスが必要です ⚠️

この MCP サーバーのツールを使用する際は、project_dir パラメーターに dbt プロジェクトディレクトリの完全な絶対パスを必ず指定してください。相対パスは正しく機能しません。

// ❌ INCORRECT - Will NOT work
{
  "project_dir": "."
}

// ✅ CORRECT - Will work
{
  "project_dir": "/Users/username/path/to/your/dbt/project"
}

詳しい手順と例については、dbt MCP の使用方法に関する完全ガイドを参照してください。

利用可能なツール

サーバーでは、以下の MCP ツールを利用できます。

• dbt_run：dbt モデルを実行します（絶対パスの project_dir が必要です）
• dbt_test：dbt テストを実行します（絶対パスの project_dir が必要です）
• dbt_ls：dbt リソースを一覧表示します（絶対パスの project_dir が必要です）
• dbt_compile：dbt モデルをコンパイルします（絶対パスの project_dir が必要です）
• dbt_debug：dbt プロジェクトのセットアップをデバッグします（絶対パスの project_dir が必要です）
• dbt_deps：dbt パッケージの依存関係をインストールします（絶対パスの project_dir が必要です）
• dbt_seed：CSV ファイルをシードデータとして読み込みます（絶対パスの project_dir が必要です）
• dbt_show：モデルの結果をプレビューします（絶対パスの project_dir が必要です）

{ "models": "customers", "project_dir": "/path/to/dbt/project", "limit": 10 } </use_mcp_tool>

### dbt Profiles Configuration

When using the dbt MCP tools, it's important to understand how dbt profiles are handled:

1. The `project_dir` parameter **MUST** be an absolute path (e.g., `/Users/username/project` not `.`) that points to a directory containing both:
   - A valid `dbt_project.yml` file
   - A valid `profiles.yml` file with the profile referenced in the project

2. The MCP server automatically sets the `DBT_PROFILES_DIR` environment variable to the absolute path of the directory specified in `project_dir`. This tells dbt where to look for the profiles.yml file.

3. If you encounter a "Could not find profile named 'X'" error, it means either:
   - The profiles.yml file is missing from the project directory
   - The profiles.yml file doesn't contain the profile referenced in dbt_project.yml
   - You provided a relative path instead of an absolute path for `project_dir`

Example of a valid profiles.yml file:

```yaml
jaffle_shop:  # This name must match the profile in dbt_project.yml
  target: dev
  outputs:
    dev:
      type: duckdb
      path: 'jaffle_shop.duckdb'
      threads: 24

MCP サーバーを通じてコマンドを実行する際は、設定ファイルが両方そろった正しい構成でプロジェクトディレクトリが用意されていることを確認してください。

開発

統合テスト

このプロジェクトには、実際の dbt プロジェクトで機能を検証する統合テストが含まれています。

# Run all integration tests
python integration_tests/run_all.py

# Run a specific integration test
python integration_tests/test_dbt_run.py

テストプロジェクトのセットアップ

統合テストでは、dbt_integration_tests ディレクトリに Git サブモジュールとして含まれている jaffle_shop_duckdb プロジェクトを使用します。セットアップのセクションで説明されているように、--recurse-submodules を指定してリポジトリをクローンすると、自動的に初期化されます。

元のリポジトリからテストプロジェクトを最新バージョンに更新する必要がある場合は、次を実行してください。

git submodule update --remote dbt_integration_tests/jaffle_shop_duckdb

jaffle_shop_duckdb ディレクトリ内のファイルが見つからないというエラーが表示される場合は、サブモジュールを初期化する必要があることがあります。

git submodule update --init

ライセンス

MIT