/ 目錄 / 演練場 / dbt
● 官方 dbt-labs 🔑 需要你的金鑰

dbt

作者 dbt-labs · dbt-labs/dbt-mcp

透過代理程式檢視您的 dbt 專案與雲端任務 — 血緣關係、模型健康狀態、指標查詢及 CLI 執行,全部整合在一個 MCP 中。

dbt Labs 官方 MCP,支援 dbt Core、dbt Fusion 與 dbt Cloud/Platform。可讀取模型/來源/曝露的詮釋資料、查詢語意層、觸發 dbt Cloud 任務,以及執行 dbt CLI 指令(build、test、run)。涵蓋資料管線的完整「是什麼、在哪裡、為什麼」。

為什麼要用

核心特性

即時演示

實際使用效果

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 執行失敗。您需要了解是什麼出錯、為何出錯,而不用開五個不同的介面。

前置條件
  • dbt Cloud 帳號 + 服務金鑰 — dbt Cloud → 個人資料 → API 金鑰
  • 本機 dbt 專案(如使用 CLI 工具) — git clone 您的 dbt 儲存庫
步驟
  1. 找出失敗的執行記錄
    列出我在 dbt Cloud 中最近 10 次任務執行記錄。顯示哪些失敗及其錯誤摘要。✓ 已複製
    → 失敗的執行 ID 與時間戳記
  2. 深入分析失敗的模型
    針對失敗的執行,哪個模型最先失敗?取得其詳細資訊(SQL、說明)及上游血緣關係。✓ 已複製
    → 失敗模型與相依鏈
  3. 提出修復方案
    使用 dbt compile 在本機編譯該模型。檢查編譯後的 SQL 以找出錯誤。提出修復所需的最小變更。✓ 已複製
    → 附有說明的具體 SQL 修復方案

結果: 在 15 分鐘內完成破損模型的驗證修復。

注意事項
  • 雲端執行失敗可能是環境問題(連線/憑證),而非程式碼問題 — 在修改 SQL 前,先透過 run 工具在本機執行相同模型 — 若本機成功,則是基礎設施問題而非程式碼問題
搭配使用: sentry · linear

使用 dbt 語意層回答業務問題

👤 推動自助分析的分析工程師 ⏱ ~10 min beginner

何時使用: 利害關係人詢問「上個月各方案的 MRR 是多少?」— 您已在 dbt SL 中定義了指標。

前置條件
  • 在您的 dbt Platform 專案中啟用語意層 — dbt Cloud → 帳號設定 → 語意層
步驟
  1. 找出指標
    列出我們 SL 中可用的指標。我在找 MRR 或 monthly_revenue。✓ 已複製
    → 找到符合的指標
  2. 確認維度
    MRR 指標可以用哪些維度查詢?我想依方案和月份篩選/分組。✓ 已複製
    → 有效的維度清單
  3. 查詢並解讀
    查詢上個月的 MRR,依方案分組。以表格格式呈現結果,並說明最大貢獻者。✓ 已複製
    → 表格 + 簡短分析

結果: 利害關係人在 2 分鐘內得到可信、受管控的答案;無需撰寫臨時 SQL。

注意事項
  • 以不支援的維度查詢時,會回傳空結果而無明確錯誤訊息 — 務必先對指標呼叫 get_dimensions;不要預設維度可用
搭配使用: notion

修改核心模型前確認影響範圍

👤 即將修改基礎模型的分析工程師 ⏱ ~20 min intermediate

何時使用: 您即將修改 dim_customers。您需要先了解所有下游使用者。

步驟
  1. 取得血緣關係
    取得 dim_customers 的下游血緣關係,包括模型、曝露及所有指標。✓ 已複製
    → 完整的下游關係圖
  2. 量化影響
    針對每個下游模型,取得其 model_performance 和 model_health — 哪些是關鍵的(被曝露使用、每日執行)?✓ 已複製
    → 若出錯將受影響項目的優先清單
  3. 規劃變更
    撰寫變更計畫:需要新增哪些測試、需要通知哪些下游負責人(確認曝露),以及部署後需要監控什麼。✓ 已複製
    → 上線計畫

結果: 對共用模型的變更能有充分認知地上線,不會造成意外的爆炸半徑。

注意事項
  • 曝露只有在您有維護的情況下才存在 — BI 工具中的隱性下游無法被追蹤 — 結合您 BI 工具的 API(Looker、Tableau)來找出真實使用者;dbt 只知道已告知它的資訊

從原始來源建立暫存模型框架

👤 正在接入新資料來源的分析工程師 ⏱ ~30 min intermediate

何時使用: 新的 Fivetran/來源資料已落地。您需要為每個資料表建立 stg_* 模型與 yml 檔案。

前置條件
  • 新資料的 sources.yml 設定 — 先定義來源;代理程式從此生成暫存模型
步驟
  1. 生成來源區塊
    使用 generate_source 處理資料庫 'raw'、綱要 'stripe'。將輸出寫入 models/staging/stripe/_sources.yml。✓ 已複製
    → 填有所有資料表的來源 yml
  2. 建立暫存模型框架
    針對每個來源資料表,呼叫 generate_staging_model。將每個模型寫入 models/staging/stripe/stg_stripe__<table>.sql。✓ 已複製
    → 每個來源資料表各一個 .sql 檔案
  3. 新增文件與測試
    針對每個新的暫存模型,呼叫 generate_model_yaml。在主鍵上新增 not_null 測試。提交變更。✓ 已複製
    → 乾淨、有測試的暫存層

結果: 在幾分鐘內建立完整的暫存層;不再有複製貼上造成的差異。

注意事項
  • 生成的模型使用 SELECT * 會拉取 PII 欄位 — 生成後,在合併前明確列出欄位,並排除或雜湊任何敏感欄位
搭配使用: git

組合

與其他 MCP 搭配,撬動十倍槓桿

dbt + sentry

當 dbt 模型失敗導致下游功能中斷時,與 Sentry 的錯誤峰值進行關聯分析

找出過去 24 小時內失敗的 dbt 執行記錄。針對每筆記錄,檢查依賴這些模型資料表的服務在 Sentry 中是否有錯誤峰值。✓ 已複製
dbt + linear

針對重複發生的 dbt 測試失敗建立 Linear 錯誤回報

列出過去一週內失敗超過 3 次的 dbt 測試。針對每個測試,在 Analytics 團隊中建立包含測試詳情的 Linear 錯誤回報。✓ 已複製
dbt + notion

自動將指標文件化至 Notion 術語表

針對語意層中的每個指標,在 Metrics Glossary 資料庫中建立或更新一個 Notion 頁面,包含名稱、說明和負責人。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
list_metrics / get_dimensions / get_entities / query_metrics metric name, dimensions, filters 業務指標查詢 SL queries billable per dbt Cloud plan
execute_sql / text_to_sql sql or natural language 結合 dbt 語境的臨時 SQL 探索 Warehouse credits
get_all_models / get_model_details / get_lineage model identifiers 資料探索與影響分析 free
get_model_health / get_model_performance model id 對資料平台進行 SRE 風格的健康檢查 free
build / run / test / compile / parse / show / docs / list dbt CLI args 本機 dbt Core 使用 warehouse compute for run/test/build
list_jobs / trigger_job_run / get_job_details / cancel_job_run / retry_job_run / list_job_runs job/run IDs dbt Cloud 操作 1 Admin API call
generate_source / generate_staging_model / generate_model_yaml source/model refs 建立新模型的框架 free
get_exposures / get_exposure_details exposure name 尋找以曝露形式記錄的下游使用者 free

成本與限制

運行它的成本

API 配額
dbt Cloud Admin API:依方案而定。語意層:依方案限制。
每次呼叫 Token 數
血緣關係圖與模型清單可能很龐大 — 請使用分頁
費用
MCP 免費;dbt Core 免費;dbt Cloud/Platform 需付費。倉儲查詢費用由您的倉儲計費。
提示
可自由使用探索工具(get_model_details、get_lineage)— 這些只是詮釋資料。使用 execute_sql / query_metrics 時需謹慎,這些會觸及倉儲。

安全

權限、密鑰、影響範圍

憑證儲存: dbt Cloud 服務金鑰存放於環境變數;Core 使用您的 profiles.yml
資料出站: Cloud 工具連至 dbt Cloud(cloud.getdbt.com);SQL 工具連至您的倉儲

故障排查

常見錯誤與修復

401 on Admin API calls

服務金鑰已過期或缺少必要的帳號權限。請至 dbt Cloud → 帳號設定 → 服務金鑰重新生成。

Semantic Layer tools return 'not configured'

語意層是付費功能,且必須在每個專案中啟用。請至 dbt Cloud → 專案設定 → 語意層確認。

CLI tools (run/build) fail with 'No profile'

將 DBT_PROFILES_DIR 設定為包含 profiles.yml 的目錄,或從含有本機 profiles.yml 的專案根目錄執行。

驗證: dbt debug
get_lineage returns empty

Manifest 已過期。請先執行 parse 以重新生成 manifest.json。

替代方案

dbt 對比其他方案

替代方案何時用它替代權衡
SQLMesh MCP您使用 SQLMesh 而非 dbt不同的轉換範式;非直接替換
Direct warehouse MCPs (Snowflake, BigQuery)您只需要原始 SQL,不需要 dbt 詮釋資料失去模型/血緣關係/測試的感知能力

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills