dbt MCP Server (Official)

什么是 dbt MCP Server (Official)？

dbt MCP 服务器是 dbt Labs 官方推出的 Model Context Protocol 服务器，为 AI 智能体提供覆盖 dbt Core、dbt Fusion 和 dbt platform 的项目上下文与工具，包括血缘关系、模型元数据、Semantic Layer 指标、dbt CLI 命令和作业管理。

它有两种形式。自托管服务器通过 uvx dbt-mcp 在本机运行，适合编写模型、测试和文档等开发工作。远程服务器由 dbt 托管，地址为 https://YOUR_DBT_HOST_URL/api/ai/v1/mcp，无需安装，适合查询指标、浏览元数据和查看血缘等使用型场景。

如何使用 dbt MCP Server (Official)？

自托管前提条件： 安装 uv；如果要使用 CLI 工具，还需要一个本地 dbt 项目。无需克隆 dbt-mcp 仓库。若要使用 dbt platform 功能，需要你的访问 URL（例如 abc123.us1.dbt.com），以及 OAuth 或令牌。

关键环境变量：CLI 使用 DBT_PROJECT_DIR（包含 dbt_project.yml 的文件夹）和 DBT_PATH（dbt 可执行文件的完整路径，可用 which dbt 查找）；平台功能使用 DBT_HOST、DBT_TOKEN、DBT_PROD_ENV_ID，使用 Admin API 或 PAT 认证时还需要 DBT_ACCOUNT_ID。

Claude Desktop

最快的方式是使用 dbt-mcp.mcpb 包：从 GitHub 最新 release 下载，双击在 Claude Desktop 中打开，填写 dbt platform 主机地址并启用服务器。如需手动配置，打开 Settings > Developer > Edit Config 并添加：

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/your/dbt/executable",
        "DBT_HOST": "YOUR-ACCESS-URL"
      }
    }
  }
}

仅使用 CLI 时省略 DBT_HOST；仅使用平台功能时省略两个 CLI 变量。若要使用远程服务器，在 Chat > Customize > Connectors 中用你的 MCP URL 添加自定义连接器，并完成 OAuth 流程。

Claude Code

连接远程服务器：

claude mcp add --transport http dbt https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/

使用令牌认证时，在项目的 .mcp.json 中配置请求头：

{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token YOUR_DBT_ACCESS_TOKEN",
        "x-dbt-prod-environment-id": "DBT_PROD_ENV_ID"
      }
    }
  }
}

Cursor 和 VS Code

dbt 为两者都提供了集成指南。上面的自托管 uvx dbt-mcp 配置块可直接作为 Cursor mcp.json 中的 mcpServers 条目；在 VS Code 中，把同样的命令和环境变量放到 .vscode/mcp.json 的 servers 下。

dbt MCP Server (Official) 的主要功能

• dbt Labs 官方开源服务器（Apache-2.0）
• 支持 dbt Core、dbt Fusion 和 dbt platform
• 可通过 uvx dbt-mcp 自托管，也可通过 HTTP 远程连接，支持 OAuth 或令牌请求头
• 通过 Discovery API 获取血缘和模型健康状况，包括列级血缘
• 通过 Semantic Layer 查询指标、维度和已保存查询
• 支持 build、run、test、compile 等 dbt CLI 命令（仅自托管）
• Admin API 工具可列出、触发、取消和重试作业运行
• 可用 DISABLE_* 变量或 x-dbt-disable-tools 请求头进行精细控制

dbt MCP Server (Official) 工具

工具按工具集分组，可单独开启或关闭：

• Discovery： get_all_models、get_lineage、get_node_details、get_model_health 和 get_all_sources 用于浏览项目元数据。若干旧的详情类工具已弃用，改用 get_node_details。
• Semantic Layer： list_metrics、get_dimensions、query_metrics 和 get_metrics_compiled_sql。
• SQL： execute_sql 和 text_to_sql。自托管时默认禁用；execute_sql 需要个人访问令牌，text_to_sql 是唯一会消耗 dbt Copilot 操作额度的工具。
• dbt CLI： build、compile、run、test、show、parse、list 和 docs。这些命令可能修改你的模型和数据仓库对象。
• Admin API： list_jobs、trigger_job_run、get_job_run_error、retry_job_run 和 cancel_job_run。
• Codegen： generate_source、generate_model_yaml 和 generate_staging_model（默认关闭；需要 dbt-codegen 包）。
• dbt LSP 与文档： get_column_lineage、fusion.compile_sql，以及用于检索 docs.getdbt.com 的 search_product_docs。

dbt MCP Server (Official) 的使用场景

• 影响分析：“What models are downstream of stg_orders, and which dashboards depend on them?”
• 指标问答：通过 Semantic Layer 回答“What is the total revenue for the last 30 days?”
• 作业排错：“Why did last night's production job fail? Show the error and retry it.”
• 开发：“Generate a staging model and YAML for the raw.payments source, then run its tests.”
• 模型健康检查：“Which mart models have failing tests or stale sources?”
• 查阅文档：“Search the dbt docs for how incremental models handle schema changes.”

dbt MCP Server (Official) 与替代方案对比

主要选择在于两个官方版本之间。自托管 dbt MCP 服务器提供 CLI 命令、代码生成和本地 manifest 工具，适合开发。远程服务器无需安装，覆盖 Semantic Layer、SQL、Discovery 和文档工具，但不运行 dbt CLI 命令。如果你只需要直接查询数据仓库而不需要 dbt 上下文，Postgres MCP 这类数据库服务器更简单，但它不了解模型、血缘或指标。

dbt MCP Server (Official) 常见问题排查

• spawn uvx ENOENT 或 “Could not connect to MCP server”： 客户端找不到 uvx。运行 which uvx（macOS/Linux）或 where uvx（Windows），并将完整路径填入 command。
• OAuth 登录无法启动： 可能是残留的锁文件导致。关闭客户端，运行 rm -f ~/.dbt/mcp.yml ~/.dbt/mcp.lock，然后重启。同时确认账户管理员已启用 dbt Wizard 功能。
• 使用服务令牌时 execute_sql 失败： 它需要个人访问令牌，或在远程服务器上使用 OAuth。
• ID 被拒绝： 请使用数字值，例如 DBT_PROD_ENV_ID=54321，而不是控制台 URL。
• 缺少 SQL 或 codegen 工具： 它们默认处于禁用状态。设置 DISABLE_SQL=false 或 DISABLE_DBT_CODEGEN=false。