AI导哈

DBT CLI MCP服务

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

  • by MammothGrowth
  • Python
  • 本地部署
  • 19 星标
  • 更新于
在 GitHub 查看 MammothGrowth/dbt-cli-mcp

使用说明

DBT CLI MCP服务器

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

特性

  • 通过MCP工具执行dbt命令
  • 支持所有主要的dbt操作（运行、测试、编译等）
  • 用于直接交互的命令行界面
  • dbt项目的环境变量管理
  • 可配置的dbt可执行路径
  • 灵活的配置文件.yml位置配置

安装

先决条件

  • Python 3.10或更高版本
  • uv Python环境管理工具
  • 已安装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文件的目录路径（如果未指定，则默认为项目目录）

环境变量

还可以使用环境变量配置服务器：

  • 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 参数。相对路径将无法正常工作。

// ❌ 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

许可证

麻省理工学院

相关 MCP