dbt-labs/dbt-mcp

dbt-MCP Server – dbt 프로젝트와 AI 에이전트를 연결하는 다리

개요

• 오픈소스 서버로, Model Context Protocol (MCP)을 구현합니다. 외부 프로그램(주로 LLM 기반 에이전트)이 dbt 프로젝트(모델, 소스, 메트릭, 시맨틱 레이어, 작업 실행, 자연어 기반 SQL 생성)를 쿼리하고 조작할 수 있게 하는 풍부한 RPC 스타일 도구를 노출합니다.
• 서버는 dbt Core(로컬), dbt Fusion 또는 dbt Platform에 대해 실행할 수 있으므로 로컬 개발이든 관리형 클라우드 환경이든 동일한 에이전트 코드가 작동합니다.

AI/ML 워크플로우에 중요한 이유

• 최신 데이터 중심 AI 에이전트에는 컨텍스트가 필요합니다. 즉, 웨어하우스의 스키마, 메트릭 정의, 모델의 계보 등이 필요합니다. dbt-MCP는 이러한 컨텍스트를 구조화되고 프로그래매틱한 방식으로 에이전트에 제공합니다.
• 또한 에이전트가 행동할 수 있게 합니다. dbt 명령 실행, 작업 트리거, 컴파일된 SQL 가져오기, 코드 생성 도우미를 통한 새 모델 파일 작성 등이 가능합니다.

주요 기능 (도구 범주별)

범주	주목할 만한 도구	에이전트가 할 수 있는 일
SQL	execute_sql, text_to_sql	dbt Platform에서 임의의 SQL을 실행하거나 프로젝트의 모델 카탈로그를 사용하여 자연어 프롬프트에서 SQL을 생성합니다.
시맨틱 레이어	list_metrics, query_metrics, get_dimension_values 등	dbt 시맨틱 레이어를 검사하고 쿼리합니다. 메트릭 정의, 컴파일된 SQL, 차원 값을 검색합니다.
디스커버리	get_all_models, get_lineage, get_node_details, search (알파)	dbt DAG 전체를 탐색하고, 모든 리소스(모델, 소스, 노출, 매크로 등)의 메타데이터를 가져오고, 프로젝트 전체에서 시맨틱 검색을 수행합니다.
dbt CLI	run, build, test, compile, list 등	일반적인 dbt 명령을 원격으로 실행하여 에이전트가 모델을 구체화하거나 테스트를 실행하거나 문서를 생성할 수 있게 합니다.
관리 API	trigger_job_run, cancel_job_run, list_jobs, get_job_run_details 등	dbt Cloud 작업을 관리합니다. 시작, 모니터링, 재시도 또는 취소를 프로그래매틱하게 수행합니다.
코드 생성	generate_model_yaml, generate_source, generate_staging_model	기존 웨어하우스 메타데이터에서 보일러플레이트 dbt 파일(YAML, 소스 정의, 스테이징 모델)을 자동 생성합니다.
dbt LSP	fusion.compile_sql, fusion.get_column_lineage, get_column_lineage	Fusion 엔진(또는 로컬 dbt-LSP)을 사용하여 전체 Jinja 컨텍스트로 SQL을 컴파일하고 열 수준 계보를 추적합니다.
제품 문서	search_product_docs, get_product_doc_pages	docs.getdbt.com에서 문서를 가져옵니다. 공식 지침을 인용해야 하는 에이전트에 유용합니다.
서버 메타데이터	get_mcp_server_version, get_mcp_server_branch	실행 중인 서버 자체를 내부 검사합니다.

AI 기반 데이터 어시스턴트의 일반적인 워크플로우

1. MCP 서버를 시작합니다 (Docker 이미지 또는 python -m dbt_mcp).
2. 어시스턴트(예: Claude, Cursor, 사용자 지정 LLM 체인)가 MCP 클라이언트 라이브러리(mcpb CLI)를 통해 연결하고 dbt Platform 계정에 인증합니다.
3. 에이전트는 list_models를 쿼리하여 데이터 웨어하우스의 멘탈 모델을 구축합니다.
4. 사용자가 "지난달 활성 고객이 몇 명이었나요?"라고 묻습니다.
5. 에이전트는 text_to_sql(또는 query_metrics로 메트릭 쿼리 작성)을 호출하여 정확한 SQL을 얻고, execute_sql로 실행한 후 결과를 반환합니다.
6. 사용자가 새 메트릭을 원하면 에이전트는 generate_model_yaml과 run을 호출하여 구체화할 수 있습니다. 사용자가 dbt 코드를 작성할 필요가 없습니다.

시작하기

1. 설치 – Docker 이미지(docker pull ghcr.io/dbt-labs/dbt-mcp)를 가져오거나 저장소에서 Python 패키지를 설치합니다.
2. MCP 번들 얻기 – 최신 릴리스에서 dbt-mcp.mcpb를 다운로드하고 Anthropic의 mcpb CLI로 설치합니다(README 링크 참조).
3. 서버 실행 – dbt-mcp serve --port 8000(또는 문서에 표시된 Docker 명령).
4. 연결 – mcpb 클라이언트 또는 언어별 SDK를 사용하여 위에 나열된 도구를 호출합니다.
5. 예제 탐색 – 저장소의 examples/ 폴더에는 연결, 모델 목록, SQL 생성, 실행의 전체 라운드 트립을 보여주는 최소한의 Python 스크립트가 포함되어 있습니다.

누가 사용해야 하는가

• 최신 dbt 메타데이터가 필요한 채팅 또는 음성 어시스턴트를 구축하는 데이터 중심 AI 제품 팀.
• 셀프 서비스 보고를 위해 내부 봇에 dbt 프로젝트를 노출하려는 분석 엔지니어.
• 데이터 모델에 대한 깊은 이해를 에이전트에 제공하는 턴키 방식을 찾는 사용자 지정 에이전트 개발자(예: LangChain 도구).

제한 사항/주의 사항

• 서버는 실험적이며, 일부 도구는 더 이상 사용되지 않음으로 표시되어 향후 릴리스에서 제거될 수 있습니다.
• CLI 유형 도구(build, run, trigger_job_run)는 프로덕션 데이터를 수정할 수 있습니다. 신뢰할 수 있는 에이전트에게만 액세스를 부여하세요.
• search 도구는 알파이며 아직 일반에 공개되지 않았습니다.

추가 자료

• 공식 문서: https://docs.getdbt.com/docs/dbt-ai/about-mcp
• 소개 블로그 게시물: https://docs.getdbt.com/blog/introducing-dbt-mcp-server
• MCP 번들 CLI: https://github.com/modelcontextprotocol/mcpb

---

위의 모든 정보는 저장소의 README에서 직접 가져온 것입니다. 추가 기능은 추론되지 않았습니다.