DBT CLI MCP 服务器
包装 dbt CLI 工具的模型上下文协议 (MCP) 服务器，使 AI 编码代理能够通过标准化 MCP 工具与 dbt 项目进行交互。
特征
Related MCP server: PAELLADOC
安装
先决条件
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）
环境变量
还可以使用环境变量来配置服务器：
与 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
执照
麻省理工学院
