Skip to main content
Glama
@us-all/dbt-mcp
by us-all

@us-all/dbt-mcp

Servidor MCP para dbt: manifest.json, run_results.json, sources.json, catalog.json, además de tablas de resultados de calidad de datos (BigQuery / Postgres) bajo un MCP stdio. Construido sobre @us-all/mcp-toolkit.

Una ventana de solo lectura a tu proyecto dbt para clientes LLM. Sin disparar dbt run: solo introspección profunda, análisis del historial de ejecuciones, frescura de fuentes, cobertura de pruebas por columna, recorridos de linaje y (si tienes una tabla de resultados de calidad de datos personalizada) tendencias históricas de comprobaciones y estado de SLA por nivel.

Para disparar DAGs / historial de ejecuciones / seguimiento de logs, instala el compañero @us-all/airflow-mcp junto a este.

  • 22 herramientas en 3 categorías (dbt, quality, meta)

  • 4 Prompts de MCP para flujos de trabajo de triaje

  • 4 herramientas de agregación que reemplazan 3-5 viajes de ida y vuelta de "listar / obtener / listar"

  • Solo lectura por defecto

  • Backend híbrido: BigQuery (por defecto) o Postgres para tablas de resultados de calidad de datos; ambos importados de forma perezosa bajo demanda

Instalación

# 1. add the MCP server
pnpm add -D @us-all/dbt-mcp
# 2. add the DQ backend you actually use (only if you query custom DQ tables):
pnpm add -D @google-cloud/bigquery   # OR
pnpm add -D pg

Related MCP server: dbt-mcp

Ejecución

DBT_PROJECT_DIR=/path/to/dbt-project \
DQ_RESULTS_TABLE=my-project.data_ops.quality_checks \
npx @us-all/dbt-mcp

El servidor utiliza MCP stdio; conéctalo a Claude Desktop / Cursor / cualquier cliente MCP. Configura MCP_TRANSPORT=http para optar por el transporte HTTP transmitible (autenticación Bearer, endpoint /health).

Categorías

Categoría

Herramientas

Propósito

dbt

15 + 2 agregaciones

Analizar manifest.json / run_results.json / sources.json / catalog.json

quality

5 + 2 agregaciones

Consultar quality_checks y quality_score_daily (BQ o PG)

meta

1 (siempre activa)

search-tools para el descubrimiento de herramientas mediante lenguaje natural

Alterna con DBT_TOOLS=dbt (lista blanca) o DBT_DISABLE=quality (lista negra).

Herramientas de un vistazo

dbt (15 + 2)

dbt-list-models, dbt-get-model, dbt-list-tests, dbt-get-test, dbt-list-sources, dbt-get-source, dbt-list-exposures, dbt-list-macros, dbt-get-macro, dbt-list-runs, dbt-get-run-results, dbt-failed-tests, dbt-slow-models, dbt-coverage, dbt-graph, freshness-status, incident-context

quality (5 + 2)

dq-list-checks, dq-get-check-history, dq-failed-checks-by-dataset, dq-score-trend, dq-tier-status, failed-tests-summary, dq-score-snapshot

Prompts

Prompt

Usar cuando

investigate-failed-tests

"¿Qué se ha roto en las últimas 24 horas?"

freshness-degradation-triage

"¿Hay alguna fuente obsoleta?" (enfoque en Nivel 1 opcional)

dq-trend-report

"Dame un informe de tendencias de calidad de datos apto para interesados"

incident-triage

"Triaje de <model

source>" — agrupa todas las señales

Variables de entorno

Env

Requerido

Notas

DBT_PROJECT_DIR

sí

Raíz del proyecto dbt (donde reside dbt_project.yml)

DBT_TARGET_DIR

no

Por defecto a $DBT_PROJECT_DIR/target

DBT_RUN_HISTORY_DIR

no

Directorio opcional para el historial archivado de run_results.json

DQ_BACKEND

no

bigquery (por defecto) o postgres

DQ_RESULTS_TABLE

no

FQN de la tabla de comprobaciones (sin ella, la categoría quality da error al llamar)

DQ_SCORE_TABLE

no

FQN de la tabla de puntuación diaria

GOOGLE_APPLICATION_CREDENTIALS

no

Para el backend de BigQuery (se admite respaldo ADC)

BQ_PROJECT_ID

no

Proyecto BQ explícito (de lo contrario se infiere de ADC)

PG_CONNECTION_STRING

no

Cuando DQ_BACKEND=postgres (secreto)

DBT_ALLOW_WRITE

no

Reservado para futuras herramientas de escritura (ninguna en v0.1)

DBT_TOOLS / DBT_DISABLE

no

Alternadores de categorías

Esquema asumido de la tabla de resultados de calidad de datos (v0.1)

La categoría quality asume las columnas check_name, check_type, dataset, table_name, status, severity, failure_count, run_at, message en DQ_RESULTS_TABLE, y score_date, scope, tier, completeness_pct, freshness_pct, validity_pct, anomaly_free_pct, overall_score en DQ_SCORE_TABLE. La v0.2 añadirá una capa de mapeo de columnas configurable.

Esquemas probados

  • Esquema de manifiesto dbt v11 / v12 / v13 (otros suelen analizarse, pero una línea de caveats los marcará)

Servidor complementario

Para operaciones de DAG de Airflow (listar, ejecuciones, instancias de tareas, seguimiento de logs, disparar, limpiar), instala @us-all/airflow-mcp junto a este servidor.

Construcción

pnpm install
pnpm run build      # tsc → dist/
pnpm test           # vitest
pnpm run smoke      # spawns dist/index.js, calls initialize + tools/list (set env first)

Licencia

MIT — ver LICENSE.

Available Tools

27 tools
dbt-coverageA

Per-column test coverage for a dbt model (which columns have tests, table-level tests, coverage %)

Inputs: name, uniqueId, extractFields.

dbt-failed-testsB

Find tests that failed across the last N runs, grouped and ordered by chronic failure count

Inputs: recentRuns, extractFields.

dbt-get-macroA

Get a dbt macro: signature, raw SQL, and reverse-lookup of nodes that call it

Inputs: name, uniqueId, extractFields.

dbt-get-modelA

Get a single dbt model: refs, sources, columns (with catalog types if available), attached tests, raw/compiled SQL

Inputs: name, uniqueId, extractFields, includeCompiledSql.

dbt-get-run-resultsB

Get per-node results from a specific dbt invocation (or the latest run if invocationId omitted)

Inputs: limit, status, invocationId, extractFields.

dbt-get-sourceA

Get a single dbt source: freshness criteria, columns, latest freshness result from sources.json

Inputs: uniqueId, tableName, sourceName, extractFields.

dbt-get-testA

Get a single dbt test: definition, parameters, attached models, latest run result

Inputs: uniqueId (required), extractFields.

dbt-graphB

Walk dbt parent_map / child_map to return upstream and downstream nodes (model/source/test) up to a given depth

Inputs: name, uniqueId, extractFields, upstreamDepth, +1 more.

dbt-list-exposuresA

List dbt exposures (downstream BI/ML/application consumers declared in YAML)

Inputs: limit, search, exposureType, extractFields.

dbt-list-macrosA

List dbt macros from manifest.json with package / name filters

Inputs: limit, search, package, extractFields.

dbt-list-modelsA

List dbt models from manifest.json with filters (package, tag, materialized, schema, name search)

Inputs: tag, limit, schema, search, +3 more.

dbt-list-runsC

List recent dbt invocations from run_results.json files in target/ and DBT_RUN_HISTORY_DIR

Inputs: limit, extractFields.

dbt-list-sourcesC

List dbt sources from manifest.json with optional source-group / name filters

Inputs: limit, search, sourceName, extractFields.

dbt-list-testsC

List dbt tests (generic or singular) optionally filtered to a specific model

Inputs: limit, search, testKind, attachedTo, +1 more.

dbt-sla-statusB

Compare latest dbt run test pass rate and source freshness pass rate against DBT_SLA_CONFIG_PATH thresholds (dbt_sla.test_pass_pct / freshness_pass_pct). Returns per-axis passPct/target/meeting plus caveats when SLA fields or artifacts are missing.

Inputs: extractFields.

dbt-slow-modelsB

Top N slowest models in a dbt run by execution_time, with bytes_processed when available

Inputs: topN, invocationId, extractFields.

dq-failed-checks-by-datasetB

Group failing checks by dataset across a recent window with the latest 5 failures per dataset

Inputs: topN, sinceHours, extractFields.

dq-get-check-historyC

Time-series of one check_name's status across the last N days

Inputs: checkName (required), days, limit, extractFields.

dq-list-checksA

List recent rows from DQ_RESULTS_TABLE filtered by dataset / status / type / time window

Inputs: type, limit, status, dataset, +2 more.

dq-score-snapshotA

Aggregated 4-axis score trend + today's Tier compliance + most recent failing checks. Combines dq-score-trend + dq-tier-status + dq-list-checks(fail).

Inputs: days, extractFields, includeFailing.

dq-score-trendB

Time-series of the 4-axis DQ score (completeness / freshness / validity / anomaly_free) plus overall_score from DQ_SCORE_TABLE

Inputs: days, scope, extractFields.

dq-tier-by-sourceA

Per-tier rollup computed from quality_checks grouped by source. Reads source-to-tier mapping from dbt sources.yml meta.tier and tier targets from DBT_SLA_CONFIG_PATH (falls back to defaults). Reports per-source pass rate, meeting/missing per tier, and untiered sources as caveats.

Inputs: date, mode, sinceHours, sourceFilter, +1 more.

dq-tier-statusA

Compare today's overall_score per scope against Tier SLA targets (defaults Tier 1 99.5 / 2 99.0 / 3 95.0; override via DBT_SLA_CONFIG_PATH yaml or DQ_TIER1_TARGET_PCT) and report meeting vs missing counts

Inputs: date, extractFields, fallbackMaxDays.

failed-tests-summaryA

Aggregated 24h-ish view: dbt failed tests + DQ checks failures grouped by dataset + most recent failing rows. Replaces 3+ tool calls (dbt-failed-tests + dq-failed-checks-by-dataset + dq-list-checks).

Inputs: recentRuns, sinceHours, extractFields.

freshness-statusB

Cross-reference dbt source freshness criteria with sources.json results in a single 'is anything stale right now?' answer.

Inputs: failingOnly, extractFields.

incident-contextA

Single asset deep-dive: dbt definition + recent test failures + DQ checks for the dataset. Designed to anchor an LLM-driven incident triage.

Inputs: modelName, sourceFqn, sinceHours, extractFields.

search-toolsA

Discover available dbt MCP tools by natural language query across dbt / quality / meta categories.

Inputs: query (required), limit, category.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools have distinct purposes, but composite tools like `failed-tests-summary` overlap with `dbt-failed-tests` and `dq-failed-checks-by-dataset`, and `incident-context` aggregates multiple individual tools, potentially causing confusion about which to use.

    Naming Consistency3/5

    Tools follow a consistent prefix pattern (`dbt-` and `dq-`) but there are deviations like `dbt-graph` instead of `dbt-get-graph`, and four tools without any prefix (`failed-tests-summary`, `freshness-status`, `incident-context`, `search-tools`), mixing naming conventions.

    Tool Count4/5

    With 27 tools covering dbt core operations, data quality, and incident triage, the count is slightly high but well-justified for the broad scope, avoiding the extremes of overwhelming or insufficient coverage.

    Completeness4/5

    The tool set covers essential dbt monitoring and data quality workflows (listing, details, failures, SLAs, scores), but lacks write operations and some administrative functions, though that seems intentional for a read-only analysis server.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      AI-driven MCP server that audits, profiles, detects schema drift, and auto-generates documentation for dbt projects, enabling natural language interaction with your dbt project's health.
      105
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides tools to interact with dbt, including dbt Core, Cloud CLI, Semantic Layer, and Discovery API.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A production-ready MCP server that provides comprehensive dbt project quality assessment for any GitHub repository, enabling AI agents to analyze dbt models, check metadata coverage, and map data lineage.
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing read-only Snowflake metadata tools (schemas, tables, queries, lineage) for agentic data pipeline generation, enabling natural-language-to-pipeline workflows with dbt, Airflow, and Great Expectations.
      1
      MIT