DBT CLI MCP 서버

dbt CLI 도구를 래핑하는 MCP(Model Context Protocol) 서버로, AI 코딩 에이전트가 표준화된 MCP 도구를 통해 dbt 프로젝트와 상호 작용할 수 있도록 합니다.

특징

MCP 도구를 통해 dbt 명령 실행
모든 주요 DBT 작업(실행, 테스트, 컴파일 등) 지원
직접 상호 작용을 위한 명령줄 인터페이스
DBT 프로젝트에 대한 환경 변수 관리
구성 가능한 dbt 실행 파일 경로
유연한 profiles.yml 위치 구성

설치

필수 조건

Python 3.10 이상
Python 환경 관리를 위한 uv 도구
dbt CLI 설치됨

설정

지엑스피1

용법

명령줄 인터페이스

이 패키지는 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 필요)

{ "모델": "고객", "프로젝트 디렉토리": "/경로/dbt/프로젝트", "제한": 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

dbt CLI MCP Server

Integrations