dbt CLI

Un servidor MCP que envuelve la CLI de dbt, permitiendo que agentes de IA interactúen con proyectos de dbt.

GitHub
18
Prueba este MCPPatrocinado

Documentación

Servidor MCP de dbt CLI

Un servidor de Model Context Protocol (MCP) que envuelve la herramienta CLI de dbt, permitiendo que agentes de codificación con IA interactúen con proyectos 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 (run, test, compile, etc.)
  • Interfaz de línea de comandos para interacción directa
  • Gestión de variables de entorno para proyectos dbt
  • Ruta configurable del ejecutable de dbt
  • Configuración flexible de la ubicación de profiles.yml

Instalación

Requisitos previos

  • Python 3.10 o superior
  • uv herramienta para la gestión del entorno de 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 usar 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 de 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 (por defecto, project-dir si no se especifica)

Variables de entorno

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

  • DBT_PATH: Ruta al ejecutable de 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 usar el servidor con un cliente MCP como Claude para Desktop, agrégalo 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, DEBES especificar la RUTA ABSOLUTA COMPLETA a tu directorio de 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"
}

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

Herramientas disponibles

El servidor proporciona las siguientes herramientas MCP:

  • dbt_run: Ejecutar modelos dbt (requiere project_dir absoluta)
  • dbt_test: Ejecutar pruebas dbt (requiere project_dir absoluta)
  • dbt_ls: Listar recursos dbt (requiere project_dir absoluta)
  • dbt_compile: Compilar modelos dbt (requiere project_dir absoluta)
  • dbt_debug: Depurar la configuración del proyecto dbt (requiere project_dir absoluta)
  • dbt_deps: Instalar dependencias de paquetes dbt (requiere project_dir absoluta)
  • dbt_seed: Cargar archivos CSV como datos semilla (requiere project_dir absoluta)
  • dbt_show: Previsualizar resultados del modelo (requiere project_dir absoluta)

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

Al ejecutar comandos a través del servidor MCP, asegúrate de que tu directorio de 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 contra 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 usan el proyecto jaffle_shop_duckdb que se incluye como submódulo de Git en el directorio dbt_integration_tests. Cuando clonas el repositorio con --recurse-submodules como se menciona en la sección de Configuración, esto se inicializará automáticamente.

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

git submodule update --remote dbt_integration_tests/jaffle_shop_duckdb

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

git submodule update --init

Licencia

MIT