DBT CLI MCP 服务器

一个模型上下文协议 (MCP) 服务器，它封装了 dbt CLI 工具，使 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

# 使用自定义 profiles 目录运行 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 工具：

• dbt_run: 运行 dbt 模型
• dbt_test: 运行 dbt 测试
• dbt_ls: 列出 dbt 资源
• dbt_compile: 编译 dbt 模型
• dbt_debug: 调试 dbt 项目设置
• dbt_deps: 安装 dbt 包依赖
• dbt_seed: 加载 CSV 文件作为种子数据
• dbt_show: 预览模型结果 <arguments> { "models": "customers", "project_dir": "/path/to/dbt/project", "limit": 10 } </arguments> </use_mcp_tool>

### dbt Profiles 配置

使用 dbt MCP 工具时，了解 dbt profiles 的处理方式非常重要：

1. `project_dir` 参数必须指向包含以下内容的目录：
   - 一个有效的 `dbt_project.yml` 文件
   - 一个有效的 `profiles.yml` 文件，其中包含项目中引用的 profile

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

3. 如果您遇到“Could not find profile named 'X'”错误，则表示：
   - profiles.yml 文件从项目目录中丢失
   - profiles.yml 文件不包含 dbt_project.yml 中引用的 profile

有效的 profiles.yml 文件示例：

```yaml
jaffle_shop:  # 此名称必须与 dbt_project.yml 中的 profile 匹配
  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