DBT CLI MCP Server

一个封装了 dbt CLI 工具的 Model Context Protocol (MCP) 服务器，允许 AI 编码代理通过标准化的 MCP 工具与 dbt 项目进行交互。

功能

• 通过 MCP 工具执行 dbt 命令
• 支持所有主要的 dbt 操作（run、test、compile 等）
• 命令行界面实现直接交互
• dbt 项目的环境变量管理
• 可配置的 dbt 可执行文件路径
• 灵活的 profiles.yml 文件位置配置

安装

先决条件

• Python 3.10 或更高版本
• 用于 Python 环境管理的 uv 工具
• 已安装的 dbt CLI

设置

# 使用子模块克隆仓库
git clone --recurse-submodules https://github.com/yourusername/dbt-cli-mcp.git
cd dbt-cli-mcp

# 如果您已经克隆但没有使用 --recurse-submodules，请初始化子模块
# git submodule update --init

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # 在 Windows 上: .venv\Scripts\activate

# 安装依赖项
uv pip install -e .

# 对于开发，安装开发依赖项
uv pip install -e ".[dev]"

使用方法

命令行界面

该包提供了一个命令行界面，用于直接与 dbt 进行交互：

# 运行 dbt 模型
dbt-mcp run --models customers --project-dir /path/to/project

# 使用自定义配置目录运行 dbt 模型
dbt-mcp run --models customers --project-dir /path/to/project --profiles-dir /path/to/profiles

# 列出 dbt 资源
dbt-mcp ls --resource-type model --output-format json

# 运行 dbt 测试
dbt-mcp test --project-dir /path/to/project

# 获取帮助
dbt-mcp --help
dbt-mcp run --help

您也可以直接使用模块：

python -m src.cli run --models customers --project-dir /path/to/project

命令行选项

• --dbt-path: dbt 可执行文件的路径（默认值： "dbt"）
• --env-file: 环境文件的路径（默认值：".env"）
• --log-level: 日志级别（默认值："INFO"）
• --profiles-dir: 包含 profiles.yml 文件的目录路径（如果未指定，默认为 project-dir）

环境变量

服务器也可以通过环境变量进行配置：

• DBT_PATH: dbt 可执行文件的路径
• ENV_FILE: 环境文件的路径
• LOG_LEVEL: 日志级别
• DBT_PROFILES_DIR: 包含 profiles.yml 文件的目录路径

与 MCP 客户端一起使用

要将服务器与像 Claude for Desktop 这样的 MCP 客户端一起使用，请将其添加到客户端的配置中：

{
  "mcpServers": {
    "dbt": {
      "command": "uv",
      "args": ["--directory", "/path/to/dbt-cli-mcp", "run", "src/server.py"],
      "env": {
        "DBT_PATH": "/absolute/path/to/dbt",
        "ENV_FILE": ".env"
        // 您还可以在此处设置 DBT_PROFILES_DIR 以作为服务器范围的默认值
      }
    }
  }
}

⚠️ 重要提示：必须使用绝对项目路径 ⚠️

当使用此 MCP 服务器中的任何工具时，您必须在 project_dir 参数中指定 dbt 项目的完整绝对路径。相对路径无法正确工作。

// ❌ 错误 - 将无法正常工作
{
  "project_dir": "."
}

// ✅ 正确 - 将正常工作
{
  "project_dir": "/Users/username/path/to/your/dbt/project"
}

有关更详细的说明和示例，请参阅 完整的 dbt MCP 使用指南。

可用工具

服务器提供了以下 MCP 工具：

• dbt_run: 运行 dbt 模型（需要绝对 project_dir）
• dbt_test: 运行 dbt 测试（需要绝对 project_dir）
• dbt_ls: 列出 dbt 资源（需要绝对 project_dir）
• dbt_compile: 编译 dbt 模型（需要绝对 project_dir）
• dbt_debug: 调试 dbt 项目设置（需要绝对 project_dir）
• dbt_deps: 安装 dbt 包依赖项（需要绝对 project_dir）
• dbt_seed: 加载 CSV 文件作为种子数据（需要绝对 project_dir）
• dbt_show: 预览模型结果（需要绝对 project_dir）

dbt 配置文件配置

使用 dbt MCP 工具时，了解 dbt 配置文件是如何处理的非常重要：

1. project_dir 参数必须是一个绝对路径（例如 /Users/username/project 而不是 .），指向包含以下内容的目录：

   • 有效的 dbt_project.yml 文件
   • 有效的 profiles.yml 文件，其中包含项目中引用的配置文件

2. MCP 服务器自动将 DBT_PROFILES_DIR 环境变量设置为 project_dir 中指定的目录的绝对路径。这告诉 dbt 在哪里查找 profiles.yml 文件。

3. 如果遇到“找不到名为 'X' 的配置文件”错误，这意味着：

   • 项目目录中缺少 profiles.yml 文件
   • profiles.yml 文件中不包含 dbt_project.yml 中引用的配置文件
   • 您为 project_dir 提供了相对路径而不是绝对路径

有效 profiles.yml 文件的示例：

jaffle_shop:  # 此名称必须与 dbt_project.yml 中的配置文件匹配
  target: dev
  outputs:
    dev:
      type: duckdb
      path: 'jaffle_shop.duckdb'
      threads: 24

通过 MCP 服务器运行命令时，请确保您的项目目录结构正确，并且两个配置文件都存在。

开发

集成测试

该项目包括集成测试，验证针对真实 dbt 项目的功能：

# 运行所有集成测试
python integration_tests/run_all.py

# 运行特定的集成测试
python integration_tests/test_dbt_run.py

测试项目设置

集成测试使用 jaffle_shop_duckdb 项目，它作为 Git 子模块包含在 dbt_integration_tests 目录中。当您按照设置部分所述使用 --recurse-submodules 克隆存储库时，这将自动初始化。

如果需要将测试项目更新到原始存储库的最新版本：

git submodule update --remote dbt_integration_tests/jaffle_shop_duckdb

如果看到关于 jaffle_shop_duckdb 目录中缺少文件的错误，则可能需要初始化子模块：

git submodule update --init

许可证

MIT