dbt MCP 服务器

此 MCP（模型上下文协议）服务器提供多种工具，用于与 dbt 进行交互。您可以使用此 MCP 服务器为 AI 代理提供 dbt Core、dbt Fusion 和 dbt Platform 中项目的上下文信息。

请阅读我们的文档 这里 以了解更多信息。这篇博客文章提供了关于 dbt MCP 服务器功能的更多详细信息。

实验性 MCP 包

我们会在每次发布时附带一个实验性的模型上下文协议包 (dbt-mcp.mcpb)，以便支持 MCPB 的客户端无需额外设置即可导入此服务器。请从最新版本的发布资产中下载该包，并按照 Anthropic 的 mcpb CLI 文档进行安装或检查。

反馈

如果您有任何意见或问题，请创建一个 GitHub 问题，或加入我们的 社区 Slack，在 #tools-dbt-mcp 频道中交流。

架构

dbt MCP 服务器的架构允许您的代理连接到多种工具。

工具

SQL

用于在 dbt Platform 基础设施上执行和生成 SQL 的工具。

• execute_sql: 在 dbt Platform 基础设施上执行 SQL，并支持语义层。
• text_to_sql: 根据项目上下文，将自然语言转换为 SQL。

语义层

如需了解更多关于 dbt 语义层的信息，请点击 这里。

• get_dimensions: 获取指定指标的维度。
• get_entities: 获取指定指标的实体。
• get_metrics_compiled_sql: 返回指标的编译后 SQL，但不执行查询。
• list_metrics: 检索所有已定义的指标。
• list_saved_queries: 检索所有保存的查询。
• query_metrics: 执行带有筛选和分组选项的指标查询。

Discovery

如需了解更多关于 dbt Discovery API 的信息，请点击 这里。

• get_all_macros: 检索宏；可按包筛选或仅返回包名称。
• get_all_models: 检索所有模型的名称和描述。
• get_all_sources: 获取所有数据源及其新鲜度状态；可按数据源名称筛选。
• get_exposure_details: 获取曝光详情，包括负责人、父级和新鲜度状态。
• get_exposures: 获取所有曝光（下游仪表板、应用或分析）。
• get_lineage: 获取完整的血缘图（祖先和后代），并支持按类型和深度筛选。
• get_macro_details: 获取特定宏的详细信息。
• get_mart_models: 检索所有 Mart 模型。
• get_model_children: 获取模型的下游依赖项。
• get_model_details: 获取模型的详细信息，包括编译后的 SQL、列和模式。
• get_model_health: 获取健康信号：运行状态、测试结果以及上游数据源的新鲜度。
• get_model_parents: 获取模型的上游依赖项。
• get_model_performance: 获取模型的执行历史；可选择包含测试结果。
• get_related_models: 使用语义搜索查找相似模型。
• get_seed_details: 获取特定种子的详细信息。
• get_semantic_model_details: 获取特定语义模型的详细信息。
• get_snapshot_details: 获取特定快照的详细信息。
• get_source_details: 获取数据源的详细信息，包括列和新鲜度。
• get_test_details: 获取特定测试的详细信息。
• search: [Alpha] 在整个 dbt 项目中搜索资源（尚未正式发布）。

dbt CLI

允许您的客户端通过 MCP 工具使用 dbt 命令可能会修改您的数据模型、数据源和仓库对象。请仅在您信任该客户端且清楚潜在影响的情况下继续操作。

• build: 按 DAG 顺序执行模型、测试、快照和种子。
• clone: 将选定节点从指定状态克隆到目标模式。
• compile: 从模型/测试/分析中生成可执行 SQL；可用于验证 Jinja 逻辑。
• docs: 为 dbt 项目生成文档。
• get_lineage_dev: 从本地 manifest.json 文件中检索血缘关系，并支持按类型和深度筛选。
• get_node_details_dev: 从本地 manifest.json 文件中检索节点详情（模型、种子、快照、数据源）。
• list: 按类型列出 dbt 项目中的资源，并支持选择器。
• parse: 解析并验证项目文件的语法正确性。
• run: 执行模型以将其物化到数据库中。
• show: 对数据库执行 SQL 并返回结果。
• test: 运行测试以验证数据和模型的完整性。

管理 API

如需了解更多关于 dbt 管理 API 的信息，请点击 这里。

• cancel_job_run: 取消正在运行的作业。
• get_job_details: 获取作业配置，包括触发器、计划和 dbt 命令。
• get_job_run_details: 获取运行详情，包括状态、时间、步骤和产物。
• get_job_run_error: 获取作业运行中的错误和/或警告详情；可选择仅显示警告。
• list_job_run_artifacts: 列出作业运行中可用的产物。
• list_jobs: 列出 dbt Platform 账户中的作业；可按项目或环境筛选。
• list_jobs_runs: 列出作业运行；可按作业、状态筛选，或按字段排序。
• list_projects: 列出 dbt Platform 账户中的所有项目。
• retry_job_run: 重试失败的作业运行。
• trigger_job_run: 触发作业运行；可覆盖 Git 分支、模式或其他设置。

dbt Codegen

这些工具可帮助自动化 dbt 项目文件中样板代码的生成。

• generate_model_yaml: 生成包含列的模型 YAML；可继承上游描述。
• generate_source: 通过内省数据库模式生成数据源 YAML；可选择包含列。
• generate_staging_model: 从数据源表生成暂存模型 SQL。

dbt LSP

这是一组利用 Fusion 引擎进行高级 SQL 编译和列级血缘分析的工具。

• fusion.compile_sql: 通过 dbt Platform 在项目上下文中编译 SQL。
• fusion.get_column_lineage: 通过 dbt Platform 追踪列级血缘。
• get_column_lineage: 在本地追踪列级血缘（需要通过 dbt Labs VSCE 使用 dbt-lsp）。

产品文档

用于在 docs.getdbt.com 上搜索和获取 dbt 官方文档内容的工具。

• get_product_doc_pages: 根据路径或 URL 获取一个或多个 docs.getdbt.com 页面的完整 Markdown 内容。
• search_product_docs: 在 docs.getdbt.com 中搜索与查询匹配的页面；按相关性排序后返回标题、URL 和描述。可使用 get_product_doc_pages 获取完整内容。

MCP 服务器元数据

这些工具提供有关 MCP 服务器本身的信息。

• get_mcp_server_branch: 返回正在运行的 dbt MCP 服务器的当前 Git 分支。
• get_mcp_server_version: 返回 dbt MCP 服务器的当前版本。

示例

通常，您会将 dbt MCP 服务器连接到 Claude 或 Cursor 等代理产品。不过，如果您有兴趣创建自己的代理，请查看 示例目录，了解如何入门。

依赖项

依赖项被固定为特定版本，不会自动更新。只有与安全相关的依赖项更新才会通过自动化拉取请求提交。

贡献

请阅读 CONTRIBUTING.md 文件，了解如何参与贡献！

dbt-mcp 快速上手指南

dbt-mcp 是一个基于模型上下文协议（MCP）的服务器，旨在为 AI 智能体（如 Claude、Cursor 等）提供与 dbt Core、dbt Fusion 及 dbt Platform 交互的能力。通过它，AI 可以读取项目元数据、执行 SQL、管理任务甚至生成代码。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：支持 Linux、macOS 或 Windows。
• Python 环境：建议安装 Python 3.9 或更高版本。
• dbt 项目：拥有一个已初始化的 dbt 项目，并配置好 profiles.yml。
• 访问权限：
  • 若使用 dbt Platform：需要有效的 API Key 和环境 ID。
  • 若使用 dbt Core (本地)：确保本地 dbt CLI 已安装且可正常运行。
• MCP 客户端：已安装支持 MCP 协议的 AI 编辑器或代理工具（例如 Cursor、Claude Desktop）。

注意：目前官方未提供专门的国内镜像源，请确保网络环境能够访问 GitHub 和 PyPI。

安装步骤

dbt-mcp 通常作为 MCP 服务器被客户端调用。你可以通过 Python pip 安装，或直接使用实验性的 MCP Bundle。

方法一：通过 pip 安装（推荐用于自定义配置）

1. 创建虚拟环境（可选但推荐）：

   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   

2. 安装 dbt-mcp 包：

   pip install dbt-mcp
   

3. 配置 MCP 客户端。以 Claude Desktop 为例，编辑配置文件 claude_desktop_config.json，添加以下内容：

   {
     "mcpServers": {
       "dbt": {
         "command": "python",
         "args": ["-m", "dbt_mcp"],
         "env": {
           "DBT_API_KEY": "你的_dbt_platform_api_key",
           "DBT_ENVIRONMENT_ID": "你的_environment_id"
         }
       }
     }
   }
   

   注：如果是本地 dbt Core 模式，可能不需要 DBT_API_KEY，具体取决于启动参数。

方法二：使用实验性 MCP Bundle (dbt-mcp.mcpb)

如果你使用的是支持 .mcpb 文件的客户端，可以直接下载最新 Release 中的 bundle 文件，无需手动配置 Python 环境。

1. 从 GitHub Releases 下载最新的 dbt-mcp.mcpb。
2. 使用 Anthropic 提供的 mcpb CLI 工具进行安装或检查：

   mcpb install dbt-mcp.mcpb
   

   (需先安装 mcpb CLI: pip install mcpb)

基本使用

安装并配置完成后，重启你的 AI 客户端（如 Cursor 或 Claude Desktop）。一旦连接成功，你可以直接在对话框中使用自然语言与 dbt 项目交互。

使用示例

场景 1：查询模型信息与血缘

用户输入：“帮我查找 stg_orders 模型的详细信息，包括它的上游依赖和下游应用。”

• 后台行为：AI 将自动调用 get_model_details 获取列信息和编译后的 SQL，调用 get_model_parents 获取上游依赖，并调用 get_exposures 查找下游仪表盘或应用。

场景 2：生成 SQL 与执行查询

用户输入：“查询过去 7 天内每个地区的订单总额，并按金额降序排列。”

• 后台行为：AI 利用 text_to_sql 工具，结合项目上下文生成符合 dbt 语法的 SQL，并通过 execute_sql 在 dbt Platform 基础设施上执行（需开启 Semantic Layer 支持），最后返回结果。

场景 3：自动化代码生成

用户输入：“为 raw_payments 源表生成一个 staging 模型文件和对应的 YAML 配置。”

• 后台行为：AI 调用 generate_staging_model 生成 SQL 文件，并调用 generate_model_yaml 创建包含列描述的 YAML 文件。

场景 4：诊断运行状态

用户输入：“检查昨晚失败的 job 运行报错原因。”

• 后台行为：AI 使用 list_jobs_runs 找到最近的失败记录，然后调用 get_job_run_error 提取具体的错误日志和警告信息。

---

提示：在使用 dbt CLI 类工具（如 run, build）时，请确保你信任当前的 AI 客户端，因为这些操作会直接修改数据库中的对象。