dbt MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

De primera parte — MCP oficial de dbt Labs
Funciona en dbt Core (local) + dbt Cloud/Platform (alojado)
Integración con Capa Semántica: list_metrics, query_metrics, get_dimensions
Linaje + salud de modelos + rendimiento listos para usar

Demo en vivo

Cómo se ve en la práctica

dbt.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "dbt",
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "dbt": {
      "command": {
        "path": "uvx",
        "args": [
          "dbt-mcp"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add dbt -- uvx dbt-mcp

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: dbt

Diagnostica por qué un modelo de dbt está fallando y propón una solución

👤 Ingenieros de análisis ⏱ ~15 min intermediate

Cuándo usarlo: Una ejecución de dbt programada falló. Necesitas saber qué se rompió y por qué, sin abrir 5 interfaces.

Requisitos previos

Cuenta de dbt Cloud + token de servicio — dbt Cloud → Perfil → API Tokens
Copia local del proyecto dbt (si usas herramientas CLI) — git clone tu repositorio de dbt

Flujo

Encuentra la ejecución que falló

Lista mis últimas 10 ejecuciones de trabajos en dbt Cloud. Muestra cuáles fallaron y un resumen de errores.✓ Copiado

→ IDs de ejecución que fallaron con marcas de tiempo
Profundiza en el modelo que falló

Para la ejecución que falló, ¿qué modelo falló primero? Obtén sus detalles (SQL, descripción) y su linaje ascendente.✓ Copiado

→ Modelo que falla + cadena de dependencias
Propón una solución

Ejecuta el modelo localmente con dbt compile. Inspecciona el SQL compilado para el error. Propón la edición mínima para arreglarlo.✓ Copiado

→ Solución SQL concreta con justificación

Resultado: Una solución validada para un modelo roto en menos de 15 minutos.

Errores comunes

Los fallos de ejecución en la nube pueden ser ambientales (conexión/credenciales), no de código — Antes de editar SQL, verifica si el mismo modelo se ejecuta localmente a través de la herramienta run — si sí, es infra no código

Combinar con: sentry · linear

Responde a una pregunta de negocio usando la Capa Semántica de dbt

👤 Ingenieros de análisis que habilitan autoservicio ⏱ ~10 min beginner

Cuándo usarlo: Un stakeholder pregunta '¿cuál fue MRR por plan el mes pasado?' — tienes métricas definidas en dbt SL.

Requisitos previos

Capa Semántica habilitada en tu proyecto de dbt Platform — dbt Cloud → Configuración de Cuenta → Capa Semántica

Flujo

Encuentra la métrica

Lista las métricas disponibles en nuestra SL. Busco MRR o monthly_revenue.✓ Copiado

→ Métrica coincidente encontrada
Verifica dimensiones

¿Por qué dimensiones se puede consultar la métrica MRR? Quiero filtrar/agrupar por plan y mes.✓ Copiado

→ Lista de dimensiones válida
Consulta e interpreta

Consulta MRR para el mes pasado, agrupado por plan. Formatea el resultado como una tabla y comenta sobre los mayores contribuyentes.✓ Copiado

→ Tabla + breve análisis

Resultado: El stakeholder obtiene una respuesta confiable y gobernada en 2 minutos; nadie escribió SQL ad-hoc.

Errores comunes

Consultar por una dimensión no soportada devuelve vacío sin un error claro — Siempre llama a get_dimensions en la métrica primero; no asumas

Combinar con: notion

Verifica el impacto antes de editar un modelo principal

👤 Ingenieros de análisis a punto de tocar un modelo fundamental ⏱ ~20 min intermediate

Cuándo usarlo: Estás a punto de cambiar dim_customers. Necesitas saber todos los consumidores descendentes primero.

Flujo

Obtén el linaje

Obtén el linaje descendente de dim_customers. Incluye modelos, exposiciones y cualquier métrica.✓ Copiado

→ Gráfico descendente completo
Cuantifica el impacto

Para cada modelo descendente, obtén su model_performance y model_health — ¿cuáles son críticos (usados por exposiciones, ejecutados diariamente)?✓ Copiado

→ Lista de prioridades de qué se romperá si te equivocas
Planifica el cambio

Escribe un plan de cambio: qué pruebas agregar, qué propietarios descendentes notificar (verifica exposiciones) y qué monitorear después de desplegar.✓ Copiado

→ Plan de implementación

Resultado: Los cambios en modelos compartidos se envían con conciencia, no sorpresas de radio de explosión.

Errores comunes

Las exposiciones solo existen si las mantienes — el descendente silencioso en herramientas BI no se rastrea — Combina con la API de tu herramienta BI (Looker, Tableau) para encontrar consumidores reales; dbt solo sabe lo que se le dice

Estructura modelos de staging desde fuentes sin procesar

👤 Ingenieros de análisis incorporando una nueva fuente ⏱ ~30 min intermediate

Cuándo usarlo: Llegan nuevos datos de Fivetran/fuente. Necesitas un modelo stg_* + yml para cada tabla.

Requisitos previos

Entradas de sources.yml para los nuevos datos — Define fuentes primero; el agente genera staging desde ahí

Flujo

Genera un bloque de fuente

Usa generate_source para la base de datos 'raw', esquema 'stripe'. Escribe la salida en models/staging/stripe/_sources.yml.✓ Copiado

→ YAML de fuente poblado con todas las tablas
Estructura modelos de staging

Para cada tabla de fuente, llama a generate_staging_model. Escribe cada una en models/staging/stripe/stg_stripe__<table>.sql.✓ Copiado

→ Un .sql por tabla de fuente
Agrega documentos + pruebas

Para cada nuevo modelo de staging, llama a generate_model_yaml. Agrega pruebas not_null en claves primarias. Realiza commit.✓ Copiado

→ Capa de staging limpia y probada

Resultado: Una capa de staging completa en minutos; sin desviación de copiar-pegar.

Errores comunes

Los modelos generados usan SELECT * que luego extrae columnas PII — Después de la generación, lista explícitamente columnas y excluye/hash cualquiera sensible antes de fusionar

Combinar con: git

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

dbt + sentry

Cuando una falla de modelo dbt rompe características descendentes, correlaciona con picos de error de Sentry

Encuentra ejecuciones de dbt que fallaron en las últimas 24h. Para cada una, verifica Sentry para picos de error en servicios que dependen de las tablas de esos modelos.✓ Copiado

dbt + linear

Registra bugs de Linear para fallos recurrentes de pruebas de dbt

Lista pruebas de dbt que han fallado más de 3 veces en la última semana. Para cada una, crea un bug de Linear en el equipo de Analytics con los detalles de la prueba.✓ Copiado

dbt + notion

Documentar automáticamente métricas en un glosario de Notion

Para cada métrica en nuestra Capa Semántica, crea o actualiza una página de Notion en la base de datos del Glosario de Métricas con nombre, descripción y propietario.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
list_metrics / get_dimensions / get_entities / query_metrics	nombre de métrica, dimensiones, filtros	Preguntas de métricas de negocio	Consultas SL facturables por plan de dbt Cloud
execute_sql / text_to_sql	sql o lenguaje natural	Exploración ad hoc de SQL con contexto de dbt	Créditos de almacén
get_all_models / get_model_details / get_lineage	identificadores de modelo	Descubrimiento + análisis de impacto	gratis
get_model_health / get_model_performance	id de modelo	Comprobaciones de estilo SRE en la plataforma de datos	gratis
build / run / test / compile / parse / show / docs / list	argumentos de CLI de dbt	Uso local de dbt Core	cálculo de almacén para run/test/build
list_jobs / trigger_job_run / get_job_details / cancel_job_run / retry_job_run / list_job_runs	IDs de trabajo/ejecución	Operaciones de dbt Cloud	1 llamada de API de Admin
generate_source / generate_staging_model / generate_model_yaml	referencias de fuente/modelo	Estructura de nuevos modelos	gratis
get_exposures / get_exposure_details	nombre de exposición	Encuentra consumidores descendentes documentados como exposiciones	gratis

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: API de Admin de dbt Cloud: depende del plan. Capa Semántica: límites por plan.
Tokens por llamada: Los gráficos de linaje + listas de modelos pueden ser grandes — pagina
Monetario: MCP es gratis; dbt Core es gratis; dbt Cloud/Platform es de pago. Las consultas de almacén se facturan por tu almacén.
Consejo: Usa herramientas de descubrimiento (get_model_details, get_lineage) libremente — esas son metadatos. Ten cuidado con execute_sql / query_metrics que golpean el almacén.

Seguridad

Permisos, secretos, alcance

Almacenamiento de credenciales: Token de servicio de dbt Cloud en variable de entorno; Core usa tu profiles.yml

Salida de datos: dbt Cloud (cloud.getdbt.com) para herramientas de Cloud; tu almacén para herramientas SQL

Resolución de problemas

Errores comunes y soluciones

401 en llamadas de API de Admin

Token de servicio expirado o sin la cuenta requerida. Regenera en dbt Cloud → Configuración de Cuenta → Tokens de Servicio.

Las herramientas de Capa Semántica devuelven 'no configurado'

SL es una característica de pago y debe estar habilitada por proyecto. Verifica dbt Cloud → Configuración de Proyecto → Capa Semántica.

Las herramientas CLI (run/build) fallan con 'Sin perfil'

Establece DBT_PROFILES_DIR a un directorio que contenga profiles.yml, o ejecuta desde la raíz del proyecto con un profiles.yml local.

Verificar: dbt debug

get_lineage devuelve vacío

El manifiesto está obsoleto. Ejecuta parse primero para regenerar manifest.json.

Alternativas

dbt vs otros

Alternativa	Cuándo usarla	Contrapartida
SQLMesh MCP	Usas SQLMesh en lugar de dbt	Paradigma de transformación diferente; no es un cambio directo
MCPs de almacén directo (Snowflake, BigQuery)	Solo necesitas SQL sin procesar, no metadatos de dbt	Pierdes conocimiento de modelo/linaje/prueba

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills