dbt MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

퍼스트 파티 — dbt Labs 공식 MCP
dbt Core(로컬) + dbt Cloud/Platform(호스팅)에서 작동합니다
시맨틱 레이어 통합: list_metrics, query_metrics, get_dimensions
계보 + 모델 상태 + 성능을 기본적으로 제공합니다

라이브 데모

실제 사용 모습

dbt.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "dbt",
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "dbt": {
      "command": {
        "path": "uvx",
        "args": [
          "dbt-mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add dbt -- uvx dbt-mcp

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: dbt

dbt 모델이 실패하는 이유를 진단하고 수정안을 제안합니다

👤 분석 엔지니어 ⏱ ~15 min intermediate

언제 쓸까: 예약된 dbt 실행이 실패했습니다. 5개의 UI를 열지 않고 무엇이 깨졌는지, 왜 깨졌는지 알아야 합니다.

사전 조건

dbt Cloud 계정 + 서비스 토큰 — dbt Cloud → Profile → API Tokens
로컬 dbt 프로젝트 체크아웃(CLI 도구 사용 시) — git clone your dbt repo

흐름

실패한 실행 찾기

dbt Cloud에서 최근 10개의 작업 실행을 나열합니다. 어느 것이 실패했는지 오류 요약과 함께 표시합니다.✓ 복사됨

→ 타임스탬프가 있는 실패한 실행 ID
실패한 모델로 드릴다운

실패한 실행의 경우, 어느 모델이 먼저 실패했습니까? 세부 정보(SQL, 설명) 및 업스트림 계보를 가져옵니다.✓ 복사됨

→ 실패한 모델 + 의존성 체인
수정안 제안

dbt compile을 사용하여 모델을 로컬에서 실행합니다. 컴파일된 SQL에서 오류를 검사합니다. 수정하기 위한 최소한의 편집을 제안합니다.✓ 복사됨

→ 구체적인 SQL 수정안 및 근거

결과: 깨진 모델에 대한 검증된 수정안을 15분 이내에 제공합니다.

함정

클라우드 실행 실패는 코드가 아닌 환경적 이유(연결/자격증명)일 수 있습니다 — SQL을 편집하기 전에 run 도구를 통해 같은 모델이 로컬에서 실행되는지 확인합니다 — 네라면 코드가 아닌 인프라입니다

함께 쓰기: sentry · linear

dbt 시맨틱 레이어를 사용하여 비즈니스 질문에 답변합니다

👤 셀프 서비스를 활성화하는 분석 엔지니어 ⏱ ~10 min beginner

언제 쓸까: 이해관계자가 '지난달 요금제별 MRR은 얼마였나요?'라고 묻습니다 — dbt SL에 정의된 메트릭이 있습니다.

사전 조건

dbt Platform 프로젝트에서 시맨틱 레이어 활성화됨 — dbt Cloud → Account Settings → Semantic Layer

흐름

메트릭 찾기

SL에서 사용 가능한 메트릭을 나열합니다. MRR 또는 monthly_revenue를 찾고 있습니다.✓ 복사됨

→ 일치하는 메트릭 찾음
차원 확인

MRR 메트릭을 쿼리할 수 있는 차원은 무엇입니까? 요금제와 월별로 필터링/그룹화하고 싶습니다.✓ 복사됨

→ 유효한 차원 목록
쿼리 및 해석

지난달 MRR을 요금제별로 그룹화하여 쿼리합니다. 결과를 표로 형식화하고 가장 큰 기여자에 대해 설명합니다.✓ 복사됨

→ 표 + 간단한 분석

결과: 이해관계자가 2분 내에 신뢰할 수 있는 관리되는 답변을 얻습니다. 누구도 임시 SQL을 작성하지 않습니다.

함정

지원되지 않는 차원으로 쿼리하면 명확한 오류 없이 빈 결과를 반환합니다 — 항상 메트릭에 대해 get_dimensions을 먼저 호출합니다. 가정하지 마세요.

함께 쓰기: notion

핵심 모델을 편집하기 전에 영향을 확인합니다

👤 기본 모델을 수정하려는 분석 엔지니어 ⏱ ~20 min intermediate

언제 쓸까: dim_customers를 변경하려고 합니다. 먼저 모든 다운스트림 소비자를 알아야 합니다.

흐름

계보 가져오기

dim_customers에 대한 다운스트림 계보를 가져옵니다. 모델, 노출 및 메트릭을 포함합니다.✓ 복사됨

→ 전체 다운스트림 그래프
영향 정량화

각 다운스트림 모델에 대해 model_performance 및 model_health를 가져옵니다 — 어느 것이 중요합니까(노출에 사용되고 매일 실행됨)?✓ 복사됨

→ 실수하면 깨질 것의 우선순위 목록
변경 계획

변경 계획을 작성합니다: 어떤 테스트를 추가할지, 어느 다운스트림 소유자에게 알릴지(노출 확인), 배포 후 모니터링할 내용입니다.✓ 복사됨

→ 롤아웃 계획

결과: 공유 모델에 대한 변경사항이 인식과 함께 배포되며, 영향 범위 놀라움은 없습니다.

함정

노출은 유지할 경우에만 존재합니다 — BI 도구의 조용한 다운스트림은 추적되지 않습니다 — 실제 소비자를 찾기 위해 BI 도구의 API(Looker, Tableau)와 결합합니다. dbt는 알려진 것만 압니다.

원본 소스에서 스테이징 모델 스캐폴딩

👤 새로운 소스를 온보딩하는 분석 엔지니어 ⏱ ~30 min intermediate

언제 쓸까: 새로운 Fivetran/소스 데이터가 도착합니다. 각 테이블에 대해 stg_* 모델 + yml이 필요합니다.

사전 조건

새 데이터에 대한 sources.yml 항목 — 먼저 소스를 정의합니다. 에이전트가 거기서 스테이징을 생성합니다.

흐름

소스 블록 생성

database 'raw', schema 'stripe'에 대해 generate_source를 사용합니다. 출력을 models/staging/stripe/_sources.yml에 쓰세요.✓ 복사됨

→ 모든 테이블이 채워진 소스 yml
스테이징 모델 스캐폴딩

각 소스 테이블에 대해 generate_staging_model을 호출합니다. 각각을 models/staging/stripe/stg_stripe__<table>.sql에 쓰세요.✓ 복사됨

→ 소스 테이블당 하나의 .sql
문서 + 테스트 추가

새로운 각 스테이징 모델에 대해 generate_model_yaml을 호출합니다. 기본 키에 not_null 테스트를 추가합니다. 커밋합니다.✓ 복사됨

→ 깨끗하고 테스트된 스테이징 계층

결과: 몇 분 내에 전체 스테이징 계층; 복사-붙여넣기 드리프트 없음.

함정

생성된 모델은 SELECT *를 사용하여 PII 열을 가져옵니다 — 생성 후, 병합하기 전에 열을 명시적으�� 나열하고 민감한 열을 제외/해싱합니다

함께 쓰기: git

조합

다른 MCP와 조합해 10배 효율

dbt + sentry

dbt 모델 실패가 다운스트림 기능을 중단할 때, Sentry 오류 급증과 연관시킵니다

지난 24시간 동안 실패한 dbt 실행을 찾습니다. 각각에 대해 해당 모델 테이블에 의존하는 서비스의 오류 급증을 Sentry에서 확인합니다.✓ 복사됨

dbt + linear

반복되는 dbt 테스트 실패에 대해 Linear 버그를 제출합니다

지난주에 3회 이상 실패한 dbt 테스트를 나열합니다. 각각에 대해 분석 팀에서 테스트 세부사항으로 Linear 버그를 만듭니다.✓ 복사됨

dbt + notion

메트릭을 자동으로 Notion 용어집에 문서화합니다

시맨틱 레이어의 모든 메트릭에 대해 메트릭 용어집 데이터베이스에서 이름, 설명 및 소유자와 함께 Notion 페이지를 만들거나 업데이트합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
list_metrics / get_dimensions / get_entities / query_metrics	메트릭 이름, 차원, 필터	비즈니스-메트릭 질문	dbt Cloud 요금제별 SL 쿼리 청구 대상
execute_sql / text_to_sql	SQL 또는 자연어	dbt 컨텍스트로 임시 SQL 탐색	웨어하우스 크레딧
get_all_models / get_model_details / get_lineage	모델 식별자	발견 + 영향 분석	무료
get_model_health / get_model_performance	모델 ID	데이터 플랫폼의 SRE 스타일 확인	무료
build / run / test / compile / parse / show / docs / list	dbt CLI 인자	로컬 dbt Core 사용	run/test/build을 위한 웨어하우스 컴퓨팅
list_jobs / trigger_job_run / get_job_details / cancel_job_run / retry_job_run / list_job_runs	작업/실행 ID	dbt Cloud 작업	1개 Admin API 호출
generate_source / generate_staging_model / generate_model_yaml	소스/모델 참조	새 모델 스캐폴딩	무료
get_exposures / get_exposure_details	노출 이름	노출로 문서화된 다운스트림 소비자 찾기	무료

비용 및 제한

운영 비용

API 쿼터: dbt Cloud Admin API: 요금제에 따라 다릅니다. 시맨틱 레이어: 요금제별 제한
호출당 토큰: 계보 그래프 + 모델 목록은 클 수 있습니다 — 페이지 매김
금액: MCP는 무료입니다. dbt Core는 무료입니다. dbt Cloud/Platform은 유료입니다. 웨어하우스 쿼리는 웨어하우스에서 청구합니다.
팁: 발견 도구(get_model_details, get_lineage)를 자유롭게 사용합니다 — 이것들은 메타데이터입니다. 웨어하우스에 접근하는 execute_sql / query_metrics를 조심합니다.

보안

권한, 시크릿, 파급범위

자격 증명 저장: dbt Cloud 서비스 토큰은 환경 변수에; Core는 profiles.yml을 사용합니다

데이터 외부 송신: 클라우드 도구의 경우 dbt Cloud(cloud.getdbt.com); SQL 도구의 경우 웨어하우스

문제 해결

자주 발생하는 오류와 해결

Admin API 호출에 401

서비스 토큰이 만료되었거나 필요한 계정이 없습니다. dbt Cloud → Account Settings → Service Tokens에서 다시 생성합니다.

시맨틱 레이어 도구가 '구성되지 않음'을 반환합니다

SL은 유료 기능이며 프로젝트당 활성화되어야 합니다. dbt Cloud → Project Settings → Semantic Layer를 확인합니다.

CLI 도구(run/build)가 '프로필 없음'으로 실패합니다

DBT_PROFILES_DIR을 profiles.yml을 포함하는 디렉토리로 설정하거나 로컬 profiles.yml을 사용하여 프로젝트 루트에서 실행합니다.

확인: dbt debug

get_lineage가 빈 결과를 반환합니다

매니페스트가 오래되었습니다. manifest.json을 다시 생성하기 위해 먼저 parse를 실행합니다.

대안

dbt 다른 것과 비교

대안	언제 쓰나	단점/장점
SQLMesh MCP	dbt 대신 SQLMesh를 사용합니다	다른 변환 패러다임; 직접적인 대체가 아닙니다
직접 웨어하우스 MCPs(Snowflake, BigQuery)	dbt 메타데이터가 아닌 원본 SQL만 필요합니다	모델/계보/테스트 인식을 잃습니다

dbt

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: dbt

dbt 모델이 실패하는 이유를 진단하고 수정안을 제안합니다

사전 조건

흐름

함정

dbt 시맨틱 레이어를 사용하여 비즈니스 질문에 답변합니다

사전 조건

흐름

함정

핵심 모델을 편집하기 전에 영향을 확인합니다

흐름

함정

원본 소스에서 스테이징 모델 스캐폴딩

사전 조건

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

dbt 다른 것과 비교

더 보기

리소스