DBT CLI MCP サーバー

dbt CLI ツールをラップするモデルコンテキストプロトコル (MCP) サーバー。AI コーディングエージェントが標準化された MCP ツールを通じて dbt プロジェクトと対話できるようになります。

特徴

MCPツールを通じてdbtコマンドを実行する
すべての主要な dbt 操作 (実行、テスト、コンパイルなど) のサポート
直接対話するためのコマンドラインインターフェース
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

ライセンス

マサチューセッツ工科大学

dbt CLI MCP Server

Integrations