configuring-dbt-mcp-server

配置 dbt MCP 服务

概述

dbt MCP 服务将 AI 工具连接到 dbt 的 CLI、Semantic Layer、Discovery API 和 Admin API。本指南将根据你的使用场景，指导你完成正确的配置。

决策流程

flowchart TB
    start([User wants dbt MCP]) --> q1{Local or Remote?}
    q1 -->|dev workflows,<br>CLI access needed| local[Local Server<br>uvx dbt-mcp]
    q1 -->|consumption only,<br>no local install| remote[Remote Server<br>HTTP endpoint]
    local --> q2{Which client?}
    remote --> q2
    q2 --> claude_desktop[Claude Desktop]
    q2 --> claude_code[Claude Code]
    q2 --> cursor[Cursor]
    q2 --> vscode[VS Code]
    claude_desktop --> config[Generate config<br>+ test setup]
    claude_code --> config
    cursor --> config
    vscode --> config

要询问的问题

1. 服务类型

询问：“你想使用本地还是远程 dbt MCP 服务？”

本地服务	远程服务
通过 uvx 在你的计算机上运行	通过 HTTP 连接到 dbt 平台
开发时必需（编写模型、测试、文档），也可连接到 dbt 平台进行使用（查询指标、探索元数据）	最适合用于使用（查询指标、探索元数据）
支持 dbt CLI 命令（run、build、test、show）	不支持 CLI 命令（run、build、test）
无需 dbt 平台账号，也可连接到 dbt 平台进行开发（编写模型、测试、文档）	需要 dbt 平台账号
不消耗额度	消耗 dbt Copilot 额度

2. MCP 客户端

询问：“你使用的是哪个 MCP 客户端？”

• Claude Desktop
• Claude Code（CLI）
• Cursor
• VS Code

3. 使用场景（仅限本地服务）

询问：“你的使用场景是什么？”

仅 CLI	仅平台	平台 + CLI
dbt Core/Fusion 用户	没有本地项目的 dbt Cloud 用户	完整访问两者
无需平台账号	OAuth 或令牌身份验证	需要路径 + 凭据

4. 要启用的工具

询问：“你想启用哪些工具？”（显示默认设置）

工具类别	默认设置	环境变量
dbt CLI（run、build、test、compile）	已启用	使用 DISABLE_DBT_CLI=true 禁用
Semantic Layer（指标、维度）	已启用	使用 DISABLE_SEMANTIC_LAYER=true 禁用
Discovery API（模型、血缘）	已启用	使用 DISABLE_DISCOVERY=true 禁用
Admin API（作业、运行）	已启用	使用 DISABLE_ADMIN_API=true 禁用
SQL（text_to_sql、execute_sql）	已禁用	使用 DISABLE_SQL=false 启用
Codegen（生成模型/源）	已禁用	使用 DISABLE_DBT_CODEGEN=false 启用

前置条件

本地服务

1. 安装 uv：https://docs.astral.sh/uv/getting-started/installation/
2. 准备一个 dbt 项目（用于 CLI 命令）
3. 查找路径：
   • DBT_PROJECT_DIR：包含 dbt_project.yml 的文件夹
     • macOS/Linux：在项目文件夹中运行 pwd
     • Windows：使用正斜杠的完整路径（例如 C:/Users/name/project）
   • DBT_PATH：dbt 可执行文件的路径
     • macOS/Linux：运行 which dbt
     • Windows：运行 where dbt

远程服务

1. dbt Cloud 账号，并启用了 AI 功能
2. 生产环境 ID（在 Orchestration 页面中获取）
3. 个人访问令牌或服务令牌

有关如何获取令牌和 ID 的详细说明，请参阅如何查找凭据。

凭据安全

• 始终使用环境变量引用（例如，${DBT_TOKEN}），不要在可能提交到版本控制的配置文件中使用字面令牌值
• 切勿在终端输出中记录、显示或回显令牌值
• 使用 .env 文件时，请确保将其添加到 .gitignore，以防意外提交
• 建议用户定期轮换令牌，并使用满足需求所需的最小权限集

配置模板

本地服务 - 仅 CLI

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

本地服务 - 平台 + CLI（OAuth）

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "https://your-subdomain.us1.dbt.com",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

本地服务 - 平台 + CLI（令牌认证）

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "${DBT_TOKEN}",
        "DBT_ACCOUNT_ID": "${DBT_ACCOUNT_ID}",
        "DBT_PROD_ENV_ID": "${DBT_PROD_ENV_ID}",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

本地服务 - 使用 .env 文件

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["--env-file", "/path/to/.env", "dbt-mcp"]
    }
  }
}

.env 文件内容：

DBT_HOST=cloud.getdbt.com
DBT_TOKEN=<set-via-env-or-secret-manager>
DBT_ACCOUNT_ID=<your-account-id>
DBT_PROD_ENV_ID=<your-prod-env-id>
DBT_DEV_ENV_ID=<your-dev-env-id>
DBT_USER_ID=<your-user-id>
DBT_PROJECT_DIR=/path/to/project
DBT_PATH=/path/to/dbt

远程服务

{
  "mcpServers": {
    "dbt": {
      "url": "https://cloud.getdbt.com/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token ${DBT_TOKEN}",
        "x-dbt-prod-environment-id": "${DBT_PROD_ENV_ID}"
      }
    }
  }
}

SQL/Fusion 工具的其他标头：

{
  "headers": {
    "Authorization": "Token ${DBT_TOKEN}",
    "x-dbt-prod-environment-id": "${DBT_PROD_ENV_ID}",
    "x-dbt-dev-environment-id": "${DBT_DEV_ENV_ID}",
    "x-dbt-user-id": "${DBT_USER_ID}"
  }
}

客户端专属设置

Claude Desktop

1. 点击系统菜单栏中的 Claude 菜单（不在应用内）
2. 选择 设置...
3. 转到 开发者选项卡
4. 点击 编辑配置
5. 添加 JSON 配置
6. 保存并重启 Claude Desktop
7. **验证：**查看输入框右下角是否显示 MCP 服务指示器

配置位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

Claude Code（CLI）

运行：

claude mcp add dbt -s user -- uvx dbt-mcp

这会将服务添加到你的用户范围/配置中（在此系统上为：~/.claude.json）。

要进行项目专属设置，请运行：

claude mcp add dbt -s project -- uvx dbt-mcp

这会将服务添加到项目根目录中的 .mcp.json。

或者，你也可以使用下面的手动配置。

手动配置： 编辑 ~/.claude.json（用户范围），或在项目根目录中创建 .mcp.json（项目范围）：

• ~/.claude.json：适用于所有项目的全局配置
• .mcp.json：项目专属配置，可提交到版本控制以供团队共享。如果使用令牌认证，请使用环境变量引用——切勿提交字面令牌。

对于项目专属的 dbt 设置，请使用 .mcp.json，以便团队共享相同配置。

创建配置后，请确保将 JSON 配置添加到 mcpServers 键下。

Cursor

1. 打开 Cursor 菜单 → 设置 → Cursor 设置 → MCP
2. 添加 JSON 配置
3. 更新路径和凭据
4. 保存

VS Code

1. 打开 命令面板（Cmd/Ctrl + Shift + P）
2. 运行 "MCP: Open User Configuration"（项目专属配置请选择 Workspace）
3. 添加 JSON 配置（注意：VS Code 使用 servers，而非 mcpServers）：

{
  "servers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

4. 打开 设置 → 功能 → 聊天 → 启用 MCP
5. **验证：**从命令面板运行 "MCP: List Servers"

**WSL 用户：**请在远程设置中配置，而非本地用户设置：

• 从命令面板运行 "Preferences: Open Remote Settings"
• 使用完整的 Linux 路径（例如，/home/user/project，而不是 Windows 路径）

验证步骤

测试本地服务配置

推荐：使用 .env 文件

1. 在项目根目录中创建一个 .env 文件，并添加 CLI 工具所需的最少环境变量：

DBT_PROJECT_DIR=/path/to/project
DBT_PATH=/path/to/dbt

2. 测试服务：

uvx --env-file .env dbt-mcp

替代方式：环境变量

# Temporary test (variables only last for this session)
export DBT_PROJECT_DIR=/path/to/project
export DBT_PATH=/path/to/dbt
uvx dbt-mcp

没有错误即表示配置成功。

在客户端中验证

完成设置后，询问 AI：

• “你可以使用哪些 dbt 工具？”
• “列出我的 dbt 指标”（如果已启用 Semantic Layer）
• “显示我的 dbt 模型”（如果已启用 Discovery）

常见问题及解决方法请参阅故障排除。

支持的变量完整列表请参阅环境变量参考。