DBT CLI MCP Server

这是一个封装了dbt CLI工具的模型上下文协议（MCP）服务器，使AI编码代理能够通过标准化的MCP工具与dbt项目进行交互。

特性

• 通过MCP工具执行dbt命令
• 支持所有主要的dbt操作（运行、测试、编译等）
• 命令行界面以直接交互
• 管理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-mcpls --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） <arguments>

{ "models": "customers", "project_dir": "/path/to/dbt/project", "limit": 10 } </arguments> </use_mcp_tool>

### dbt Profiles配置

在使用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文件的有效示例：

```yaml
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