DBT CLI MCP Server

DBT CLI MCP 服务

一种模型上下文协议（MCP）服务，用于封装 dbt CLI 工具，使 AI 编码 Agent 能够通过标准化的 MCP 工具与 dbt 项目交互。

功能

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

安装

先决条件

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

设置

# Clone the repository with submodules
git clone --recurse-submodules https://github.com/yourusername/dbt-cli-mcp.git
cd dbt-cli-mcp

# If you already cloned without --recurse-submodules, initialize the submodule
# git submodule update --init

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# For development, install development dependencies
uv pip install -e ".[dev]"

用法

命令行界面

此软件包提供命令行界面，可直接与 dbt 交互：

# Run dbt models
dbt-mcp run --models customers --project-dir /path/to/project

# Run dbt models with a custom profiles directory
dbt-mcp run --models customers --project-dir /path/to/project --profiles-dir /path/to/profiles

# List dbt resources
dbt-mcp ls --resource-type model --output-format json

# Run dbt tests
dbt-mcp test --project-dir /path/to/project

# Get help
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"
        // You can also set DBT_PROFILES_DIR here for a server-wide default
      }
    }
  }
}

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

使用此 MCP 服务中的任何工具时，必须通过 project_dir 参数指定 dbt 项目目录的完整绝对路径。相对路径无法正常使用。

// ❌ INCORRECT - Will NOT work
{
  "project_dir": "."
}

// ✅ CORRECT - Will work
{
  "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 必须是绝对路径）

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

### dbt Profiles Configuration

When using the dbt MCP tools, it's important to understand how dbt profiles are handled:

1. The `project_dir` parameter **MUST** be an absolute path (e.g., `/Users/username/project` not `.`) that points to a directory containing both:
   - A valid `dbt_project.yml` file
   - A valid `profiles.yml` file with the profile referenced in the project

2. The MCP server automatically sets the `DBT_PROFILES_DIR` environment variable to the absolute path of the directory specified in `project_dir`. This tells dbt where to look for the profiles.yml file.

3. If you encounter a "Could not find profile named 'X'" error, it means either:
   - The profiles.yml file is missing from the project directory
   - The profiles.yml file doesn't contain the profile referenced in dbt_project.yml
   - You provided a relative path instead of an absolute path for `project_dir`

Example of a valid profiles.yml file:

```yaml
jaffle_shop:  # This name must match the profile in dbt_project.yml
  target: dev
  outputs:
    dev:
      type: duckdb
      path: 'jaffle_shop.duckdb'
      threads: 24

通过 MCP 服务运行命令时，请确保项目目录结构正确，并且包含这两个配置文件。

开发

集成测试

此项目包含集成测试，用于验证其对真实 dbt 项目的功能：

# Run all integration tests
python integration_tests/run_all.py

# Run a specific integration test
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