/ 目录 / 演练场 / dbt
● 官方 dbt-labs 🔑 需要你的密钥

dbt

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

通过一个 agent 检查你的 dbt 项目和 Cloud 任务——血缘关系、模型健康状况、指标查询和 CLI 运行,全部在一个 MCP 里。

dbt Labs 官方的 MCP,支持 dbt Core、dbt Fusion 和 dbt Cloud/Platform。读取模型/源/exposure 元数据,查询 Semantic Layer,触发 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 运行失败了。你需要知道什么坏了以及为什么,而不用打开 5 个 UI。

前置条件
  • dbt Cloud 账户 + service token — dbt Cloud → Profile → API Tokens
  • 本地 dbt 项目检出(如果使用 CLI 工具) — git clone 你的 dbt repo
步骤
  1. 找到失败的运行
    列出我在 dbt Cloud 中最后 10 个任务运行。显示哪些失败了以及它们的错误摘要。✓ 已复制
    → 失败的运行 ID 和时间戳
  2. 深入失败的模型
    对于失败的运行,哪个模型首先失败了?获取它的详细信息(SQL、描述)和它的上游血缘关系。✓ 已复制
    → 失败的模型 + 依赖链
  3. 提出修复
    用 dbt compile 在本地运行模型。检查编译的 SQL 找错误。提出最小的编辑来修复。✓ 已复制
    → 具体的 SQL 修复及其原因

结果: 在 15 分钟内对一个损坏的模型进行验证的修复。

注意事项
  • Cloud 运行失败可能是环境问题(连接/凭据),而不是代码问题 — 在编辑 SQL 之前,检查相同的模型是否通过 run 工具在本地运行——如果是,那就是基础设施而不是代码问题
搭配使用: sentry · linear

使用 dbt Semantic Layer 回答业务问题

👤 启用自助分析的数据分析师 ⏱ ~10 min beginner

何时使用: 一个利益相关者问'上个月按计划的 MRR 是多少?'——你在 dbt SL 中定义了指标。

前置条件
  • 在你的 dbt Platform 项目上启用 Semantic Layer — dbt Cloud → Account Settings → Semantic Layer
步骤
  1. 找到指标
    列出我们 SL 中可用的指标。我在寻找 MRR 或 monthly_revenue。✓ 已复制
    → 找到匹配的指标
  2. 检查维度
    MRR 指标可以按哪些维度查询?我想按计划和月份过滤/分组。✓ 已复制
    → 有效的维度列表
  3. 查询和解释
    查询上个月的 MRR,按计划分组。将结果格式化为表格,并评论最大的贡献者。✓ 已复制
    → 表格 + 简要分析

结果: 利益相关者在 2 分钟内获得可信的、受管理的答案;没有人编写临时 SQL。

注意事项
  • 按不支持的维度查询会返回空结果,没有清晰的错误提示 — 总是先在指标上调用 get_dimensions;不要假设
搭配使用: notion

编辑核心模型前检查影响

👤 即将修改基础模型的数据分析师 ⏱ ~20 min intermediate

何时使用: 你即将更改 dim_customers。你需要先知道每一个下游消费者。

步骤
  1. 获取血缘关系
    获取 dim_customers 的下游血缘关系。包括模型、exposure 和任何指标。✓ 已复制
    → 完整的下游图表
  2. 量化影响
    对于每个下游模型,获取它的 model_performance 和 model_health——哪些是关键的(被 exposure 使用,每天运行)?✓ 已复制
    → 如果你搞砸了会坏的东西的优先级列表
  3. 规划变更
    写一个变更计划:要添加什么测试、要通知哪些下游所有者(检查 exposure)、以及部署后要监视什么。✓ 已复制
    → 推出计划

结果: 对共享模型的更改在有意识的情况下部署,而不是造成意外的爆炸半径。

注意事项
  • Exposure 只在你维护它们时存在——BI 工具中的静默下游不被追踪 — 结合你的 BI 工具的 API(Looker、Tableau)来找真正的消费者;dbt 只知道它被告知的内容

从原始源创建临时模型

👤 加入新源的数据分析师 ⏱ ~30 min intermediate

何时使用: 新的 Fivetran/源数据到达。你需要为每个表创建一个 stg_* 模型 + yml。

前置条件
  • 新数据的 sources.yml 条目 — 先定义源;agent 从那里生成临时模型
步骤
  1. 生成源块
    对数据库 'raw' 和模式 'stripe' 使用 generate_source。将输出写入 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 bug

列出过去一周内失败超过 3 次的 dbt 测试。对于每个,在 Analytics 团队中创建一个 Linear bug,并包含测试详细信息。✓ 已复制
dbt + notion

自动将指标记录到 Notion 词汇表中

对于我们 Semantic Layer 中的每个指标,在 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 找到记录为 exposure 的下游消费者 free

成本与限制

运行它的成本

API 配额
dbt Cloud Admin API:根据计划而定。Semantic Layer:按计划限制。
每次调用 Token 数
血缘图 + 模型列表可能很大——分页
费用
MCP 免费;dbt Core 免费;dbt Cloud/Platform 是付费的。仓库查询由你的仓库计费。
提示
自由使用发现工具(get_model_details、get_lineage)——那些是元数据。小心使用 execute_sql / query_metrics,它们会访问仓库。

安全

权限、密钥、影响范围

凭据存储: dbt Cloud service token 在环境变量中;Core 使用你的 profiles.yml
数据出站: dbt Cloud(cloud.getdbt.com)用于 Cloud 工具;你的仓库用于 SQL 工具

故障排查

常见错误与修复

Admin API 调用上的 401

Service token 过期或缺少所需的账户。在 dbt Cloud → Account Settings → Service Tokens 中重新生成。

Semantic Layer 工具返回 'not configured'

SL 是付费功能,必须按项目启用。检查 dbt Cloud → Project Settings → Semantic Layer。

CLI 工具(run/build)失败,显示 'No profile'

将 DBT_PROFILES_DIR 设置为包含 profiles.yml 的目录,或从包含本地 profiles.yml 的项目根目录运行。

验证: dbt debug
get_lineage 返回空

清单已过期。首先运行 parse 来重新生成 manifest.json。

替代方案

dbt 对比其他方案

替代方案何时用它替代权衡
SQLMesh MCP你使用 SQLMesh 而不是 dbt不同的转换范例;不是直接替换
Direct warehouse MCPs (Snowflake, BigQuery)你只需要原始 SQL,不需要 dbt 元数据失去模型/血缘/测试意识

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills