Servidor MCP de DBT CLI

Un servidor de Protocolo de Contexto de Modelo (MCP) que envuelve la herramienta CLI de dbt, lo que permite que los agentes de codificación de IA interactúen con proyectos de dbt a través de herramientas MCP estandarizadas.

Características

Ejecutar comandos dbt a través de herramientas MCP
Soporte para todas las operaciones principales de dbt (ejecutar, probar, compilar, etc.)
Interfaz de línea de comandos para interacción directa
Gestión de variables de entorno para proyectos dbt
Ruta ejecutable dbt configurable
Configuración flexible de la ubicación de perfiles.yml

Instalación

Prerrequisitos

Python 3.10 o superior
Herramienta uv para la gestión del entorno Python
dbt CLI instalado

Configuración

# 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]"

Uso

Interfaz de línea de comandos

El paquete proporciona una interfaz de línea de comandos para la interacción directa con 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

También puedes utilizar el módulo directamente:

python -m src.cli run --models customers --project-dir /path/to/project

Opciones de línea de comandos

--dbt-path : Ruta al ejecutable dbt (predeterminado: "dbt")
--env-file : Ruta al archivo de entorno (predeterminado: ".env")
--log-level : Nivel de registro (predeterminado: "INFO")
--profiles-dir : Ruta al directorio que contiene el archivo profiles.yml (el valor predeterminado es project-dir si no se especifica)

Variables de entorno

El servidor también se puede configurar mediante variables de entorno:

DBT_PATH : Ruta al ejecutable dbt
ENV_FILE : Ruta al archivo de entorno
LOG_LEVEL : Nivel de registro
DBT_PROFILES_DIR : Ruta al directorio que contiene el archivo profiles.yml

Uso con clientes MCP

Para utilizar el servidor con un cliente MCP como Claude for Desktop, agréguelo a la configuración del cliente:

{
  "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
      }
    }
  }
}

⚠️ IMPORTANTE: Se requiere ruta absoluta del proyecto ⚠️

Al usar cualquier herramienta de este servidor MCP, DEBE especificar la RUTA ABSOLUTA COMPLETA del directorio de su proyecto dbt con el parámetro project_dir . Las rutas relativas no funcionarán correctamente.

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

// ✅ CORRECT - Will work
{
  "project_dir": "/Users/username/path/to/your/dbt/project"
}

Consulte la guía de uso completa de dbt MCP para obtener instrucciones y ejemplos más detallados.

Herramientas disponibles

El servidor proporciona las siguientes herramientas MCP:

dbt_run : ejecuta modelos dbt (requiere project_dir absoluto)
dbt_test : ejecuta pruebas dbt (requiere project_dir absoluto)
dbt_ls : enumera los recursos dbt (requiere project_dir absoluto)
dbt_compile : Compilar modelos dbt (requiere project_dir absoluto)
dbt_debug : depurar la configuración del proyecto dbt (requiere project_dir absoluto)
dbt_deps : instala las dependencias del paquete dbt (requiere project_dir absoluto)
dbt_seed : Cargar archivos CSV como datos de semilla (requiere project_dir absoluto)
dbt_show : Vista previa de los resultados del modelo (requiere project_dir absoluto)

{ "modelos": "clientes", "directorio_del_proyecto": "/ruta/al/proyecto/dbt", "límite": 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

Al ejecutar comandos a través del servidor MCP, asegúrese de que el directorio del proyecto esté estructurado correctamente con ambos archivos de configuración presentes.

Desarrollo

Pruebas de integración

El proyecto incluye pruebas de integración que verifican la funcionalidad frente a un proyecto dbt real:

# Run all integration tests
python integration_tests/run_all.py

# Run a specific integration test
python integration_tests/test_dbt_run.py

Configuración del proyecto de prueba

Las pruebas de integración utilizan el proyecto jaffle_shop_duckdb, incluido como submódulo de Git en el directorio dbt_integration_tests. Al clonar el repositorio con --recurse-submodules como se menciona en la sección Configuración, este se inicializará automáticamente.

Si necesita actualizar el proyecto de prueba a la última versión del repositorio original:

git submodule update --remote dbt_integration_tests/jaffle_shop_duckdb

Si ve errores sobre archivos faltantes en el directorio jaffle_shop_duckdb, es posible que deba inicializar el submódulo:

git submodule update --init

Licencia

Instituto Tecnológico de Massachusetts (MIT)

dbt CLI MCP Server

Integrations