{
  "markdown": "# @us-all/dbt-mcp\n\n> dbt MCP server — `manifest.json`, `run_results.json`, `sources.json`, `catalog.json`, plus DQ result tables (BigQuery / Postgres) behind one stdio MCP. Built on `@us-all/mcp-toolkit`.\n\nA read-only window into your dbt project for LLM clients. No `dbt run` triggering — just deep introspection, run-history analysis, source freshness, per-column test coverage, lineage walks, and (if you have a custom DQ result table) historical check trends and Tier SLA status.\n\nFor DAG triggering / run history / log tails, install the companion **[@us-all/airflow-mcp](https://www.npmjs.com/package/@us-all/airflow-mcp)** alongside.\n\n- 27 tools across 3 categories (`dbt`, `quality`, `meta`) — 21 primitive tools + 5 aggregations + 1 meta\n- 4 MCP Prompts for triage workflows\n- 5 aggregation tools that replace 3-5 round-trips of \"list / get / list\"\n- `extractFields` response projection on high-volume reads\n- Read-only by default\n- Hybrid backend: BigQuery (default) or Postgres for DQ result tables — both peer-imported lazily\n\n## Install\n\n```bash\n# 1. add the MCP server\npnpm add -D @us-all/dbt-mcp\n# 2. add the DQ backend you actually use (only if you query custom DQ tables):\npnpm add -D @google-cloud/bigquery   # OR\npnpm add -D pg\n```\n\n## Run\n\n```bash\nDBT_PROJECT_DIR=/path/to/dbt-project \\\nDQ_RESULTS_TABLE=my-project.data_ops.quality_checks \\\nnpx @us-all/dbt-mcp\n```\n\nThe server speaks MCP stdio; wire it into Claude Desktop / Cursor / any MCP client. Set `MCP_TRANSPORT=http` to opt in to Streamable HTTP transport (Bearer auth, `/health` endpoint).\n\n## Categories\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| `dbt`    | 15 + 3 aggregations | Parse `manifest.json` / `run_results.json` / `sources.json` / `catalog.json` |\n| `quality`| 6 + 2 aggregations | Query `quality_checks` and `quality_score_daily` (BQ or PG); per-tier rollup via `dq-tier-by-source` |\n| `meta`   | 1 (always on) | `search-tools` for natural-language tool discovery |\n\nToggle with `DBT_TOOLS=dbt` (allowlist) or `DBT_DISABLE=quality` (denylist).\n\n## Tools at a glance\n\n### `dbt` (15 + 3)\n\n`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`, `dbt-sla-status`\n\n### `quality` (6 + 2)\n\n`dq-list-checks`, `dq-get-check-history`, `dq-failed-checks-by-dataset`, `dq-score-trend`, `dq-tier-status`, `dq-tier-by-source`, `failed-tests-summary`, `dq-score-snapshot`\n\n### Prompts\n\n| Prompt | Use when |\n|--------|----------|\n| `investigate-failed-tests` | \"What's broken in the last 24h?\" |\n| `freshness-degradation-triage` | \"Are any sources stale?\" (Tier 1 focus optional) |\n| `dq-trend-report` | \"Give me a stakeholder-friendly DQ trend report\" |\n| `incident-triage` | \"Triage <model \\| source>\" — bundles all signals |\n\n## Environment variables\n\n| Env | Required | Notes |\n|-----|----------|-------|\n| `DBT_PROJECT_DIR` | yes | dbt project root (where `dbt_project.yml` lives) |\n| `DBT_TARGET_DIR`  | no  | Defaults to `$DBT_PROJECT_DIR/target` |\n| `DBT_RUN_HISTORY_DIR` | no | Optional dir for archived `run_results.json` history |\n| `DQ_BACKEND` | no | `bigquery` (default) or `postgres` |\n| `DQ_RESULTS_TABLE` | no | FQN of the checks table; required only for checks-based quality tools |\n| `DQ_SCORE_TABLE` | no | FQN of the score-daily table; required for score-only tools |\n| `GOOGLE_APPLICATION_CREDENTIALS` | no | For BigQuery backend (ADC fallback supported) |\n| `BQ_PROJECT_ID` | no | Explicit BQ project (otherwise inferred from ADC) |\n| `PG_CONNECTION_STRING` | no | When `DQ_BACKEND=postgres` (secret) |\n| `DQ_SCHEMA` | no | `generic` (default) or `us-all` — base schema preset for the `quality` category |\n| `DQ_COL_*` | no | Per-column overrides on top of `DQ_SCHEMA` (see below). Overrides must be simple SQL identifiers. |\n| `DQ_TIER1_TARGET_PCT` | no | Tier 1 SLA threshold for `dq-tier-status` when no `tier` column is configured (default 99.5). Superseded by `DBT_SLA_CONFIG_PATH` `tier_sla.1` if both are set. |\n| `DBT_SLA_CONFIG_PATH` | no | Optional YAML path with `tier_sla` and `dbt_sla` blocks. Drives `dq-tier-status` thresholds and `dq-tier-by-source` per-tier targets. Mtime cached. |\n| `DBT_ALLOW_WRITE` | no | Reserved for future write tools (none currently) |\n| `DBT_TOOLS` / `DBT_DISABLE` | no | Category toggles |\n\n## DQ result-table schema flavors\n\nThe `quality` category supports two schema presets via `DQ_SCHEMA`:\n\n### `DQ_SCHEMA=generic` (default)\n\nColumns assumed on `DQ_RESULTS_TABLE`: `run_at`, `check_name`, `check_type`, `dataset`, `table_name`, `status`, `severity`, `failure_count`, `message`.\n\nColumns assumed on `DQ_SCORE_TABLE`: `score_date`, `scope`, `tier`, `completeness_pct`, `freshness_pct`, `validity_pct`, `anomaly_free_pct`, `overall_score`.\n\n`dq-tier-status` rolls up by Tier 1/2/3 against the per-`scope` rows.\n\n### `DQ_SCHEMA=us-all`\n\nReal schema used at us-all (Postgres `data_ops` database):\n\n`quality_checks`: `run_date`, `check_type`, `dimension`, `source`, `target_name`, `status`, `metric_value`, `threshold`, `details (JSONB)`.\n\n`quality_score_daily`: `run_date`, `completeness_pct`, `freshness_pct`, `validity_pct`, `anomaly_free_pct`, `overall_score`, `total_checks`, `failed_checks`.\n\nIn this flavor `quality_score_daily` is one row per day (no per-scope rollup, no `tier` column). `dq-tier-status` falls back to comparing the day's `overall_score` against `DQ_TIER1_TARGET_PCT` (default 99.5).\n\n`dq-get-check-history` requires `checkName` formatted as `'<check_type>:<target_name>'` since us-all has no native `check_name` column.\n\n### Per-column overrides — `DQ_COL_*`\n\nIf your DQ tables don't match either preset, layer per-column overrides on top of `DQ_SCHEMA`. Any `DQ_COL_*` env var, when set, replaces the preset value for that single column. Unset vars keep the preset default.\n\nOverrides are validated as simple SQL identifiers to avoid injecting raw SQL through environment variables. Table names in `DQ_RESULTS_TABLE` / `DQ_SCORE_TABLE` are also validated and quoted for the configured backend.\n\n| Env var | Logical concept | Generic preset | us-all preset |\n|---------|-----------------|----------------|---------------|\n| `DQ_COL_RUN_AT`        | timestamp/date on the checks table | `run_at` | `run_date` |\n| `DQ_COL_CHECK_TYPE`    | check type / dimension family       | `check_type` | `check_type` |\n| `DQ_COL_STATUS`        | pass/fail/warn/error               | `status` | `status` |\n| `DQ_COL_DATASET`       | dataset / source / schema           | `dataset` | `source` |\n| `DQ_COL_TABLE_NAME`    | table or target name                | `table_name` | `target_name` |\n| `DQ_COL_SEVERITY`      | severity / dimension                | `severity` | `dimension` |\n| `DQ_COL_FAILURE_COUNT` | numeric failure count / metric      | `failure_count` | `metric_value` |\n| `DQ_COL_MESSAGE`       | free-text or JSON message           | `message` | `details::text` |\n| `DQ_COL_CHECK_NAME`    | natural identifier of the check     | `check_name` | _(none)_ |\n| `DQ_COL_SCORE_DATE`    | date column on the score table      | `score_date` | `run_date` |\n| `DQ_COL_SCOPE`         | scope/tenant column on score table  | `scope` | _(none)_ |\n| `DQ_COL_TIER`          | tier column on score table          | `tier` | _(none)_ |\n\nFor the three nullable columns (`DQ_COL_CHECK_NAME`, `DQ_COL_SCOPE`, `DQ_COL_TIER`), set the value to `none` / `null` / `-` to declare \"no native column\":\n- Without `check_name` → the tools synthesize one from `check_type || ':' || table_name`. `dq-get-check-history` then expects `checkName` formatted as `'<check_type>:<table_name>'`.\n- Without `scope` → `dq-score-trend`'s `scope` filter is ignored (with a caveat) and `dq-tier-status` switches to the single-`overall_score` path that compares against `DQ_TIER1_TARGET_PCT`.\n- Without `tier` → same single-`overall_score` fallback.\n\nExample — generic preset against a Postgres schema where columns happen to be named differently:\n\n```\nDQ_SCHEMA=generic\nDQ_COL_RUN_AT=checked_at\nDQ_COL_DATASET=schema_name\nDQ_COL_TABLE_NAME=tbl\nDQ_COL_FAILURE_COUNT=fail_n\nDQ_COL_CHECK_NAME=none      # synthesize from check_type+tbl\nDQ_COL_SCOPE=none           # no per-team rollup\nDQ_COL_TIER=none            # use DQ_TIER1_TARGET_PCT instead\n```\n\n## SLA config (optional) — `DBT_SLA_CONFIG_PATH`\n\nSet `DBT_SLA_CONFIG_PATH` to a YAML file to surface project-defined tier targets and DBT SLAs to the quality tools. Schema (extra keys ignored):\n\n```yaml\ndbt_sla:\n  test_pass_pct: 99.0          # consumed by dbt-sla-status (test pass rate threshold)\n  freshness_pass_pct: 99.5     # consumed by dbt-sla-status (source freshness pass rate threshold)\n\ntier_sla:\n  1: 99.5                      # tier-1 overall_score / per-source pass-rate target\n  2: 99.0\n  3: 95.0\n```\n\nWhen set, the `tier_sla` map drives:\n\n- `dq-tier-status` — per-tier rollup compares each row's `overall_score` against the matching target. Without this file, hardcoded `{1: 99.5, 2: 99.0, 3: 95.0}` is used.\n- `dq-tier-by-source` — per-source pass-rate is compared to the target for that source's tier (resolved from dbt sources.yml `meta.tier`).\n- `dq-tier-status` no-tier-column path (us-all preset / `DQ_COL_TIER=none`) — uses `tier_sla.1` as the single target. `DQ_TIER1_TARGET_PCT` env still works as a fallback when no SLA file is set.\n\nThe `dbt_sla` block drives:\n\n- `dbt-sla-status` — computes test pass rate from latest `run_results.json` and freshness pass rate from `sources.json`, then compares each axis against `dbt_sla.test_pass_pct` / `dbt_sla.freshness_pass_pct`. Returns `passPct`, `target`, `meeting` per axis plus caveats when fields or artifacts are missing.\n\nThe file is mtime-cached; edits between tool calls are picked up automatically.\n\n## Per-tier rollup from `quality_checks` — `dq-tier-by-source`\n\nFor schemas where `quality_score_daily` has only one row per day (no per-scope/tier breakdown), `dq-tier-by-source` reconstructs a per-tier picture from the raw `quality_checks` rows. Two modes:\n\n### `mode: \"source\"` (default) — group by source/dataset column\n\nUse when each row of `quality_checks` represents a check on a *source group* and the dataset/source column carries the dbt source-group name directly.\n\n1. Builds a `source_name -> tier` map from the dbt manifest's `sources.<source>.<table>.meta.tier` (first table's tier per source group).\n2. Groups `quality_checks` rows by the dataset/source column and computes pass rate per source over a date or `sinceHours` window.\n3. Looks up each source's tier and target (from SLA config or defaults), reports meeting / missing per tier.\n\n### `mode: \"table\"` — group by table_name column\n\nUse when the dataset/source column is a category (`bq` / `dbt` / `airflow`) and the actual dbt source-table identifier lives in the `table_name` / `target_name` column as `<source_group>.<table>`. Common in checks tables that consolidate signals from heterogeneous backends.\n\n1. Builds a `<source_group>.<table> -> tier` map from the manifest using each source entry's `source_name + name + meta.tier` — picks up *table-level* tier overrides naturally.\n2. Groups `quality_checks` rows by the `table_name` column. Pre-filter via `sourceFilter` (e.g. `sourceFilter: \"bq\"`) when only some categories produce parseable target names.\n3. Each rollup key is parsed as `<source_group>.<table>`; rows without a `.` or whose key is not in the manifest land in `caveats[]`.\n\nUntiered rows (no manifest `meta.tier`) and unparseable rows always appear in `caveats[]` so you can tier them or accept the gap.\n\n## Tested-against schemas\n\n- dbt manifest schema v11 / v12 — the current top version. dbt 1.7 emits v11; dbt 1.8 through 1.12 all emit v12 (the schema evolves additively in-place). Newer/unknown versions still parse, but a `caveats` line will flag them.\n\n## Companion server\n\nFor Airflow DAG operations (list, runs, task instances, log tail, trigger, clear), install [`@us-all/airflow-mcp`](https://www.npmjs.com/package/@us-all/airflow-mcp) alongside this server.\n\n## Build\n\n```bash\npnpm install\npnpm run build      # tsc → dist/\npnpm test           # vitest\npnpm run smoke      # spawns dist/index.js, calls initialize + tools/list (set env first)\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 12433,
  "sha": "bb4eb1ad038a0ad01821e591589a86d2c01b02d60e66dc71f811016717427a13",
  "repo_slug": "us-all/dbt-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_us_all_dbt_67e94fcd/readme"
}