DBT CLI MCP 服务器

包装 dbt CLI 工具的模型上下文协议 (MCP) 服务器，使 AI 编码代理能够通过标准化 MCP 工具与 dbt 项目进行交互。

特征

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

{ “模型”：“客户”， “project_dir”：“/path/to/dbt/project”， “限制”：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

执照

麻省理工学院

dbt CLI MCP Server

Integrations