dbt-agents

dbt-agents is an open-source, local-first toolkit for reviewing, querying, testing, and safely fixing dbt projects and their warehouses with AI agents.

The initial warehouse implementation targets BigQuery, while the core contracts are designed for additional adapters. The primary interfaces are an MCP server for ChatGPT/Codex and a CLI for local use and GitHub Actions.

The same policy-enforced core powers:

• a Model Context Protocol server for ChatGPT and Codex;

• a local CLI for inspection and diagnostics; and

• deterministic automation suitable for GitHub Actions.

ChatGPT and Codex plugin

The internal plugin is branded as dbt Agents and packages the existing authenticated remote connection with a guided setup workflow. From this checkout, install it with:

make plugin-install

Restart the ChatGPT desktop app, choose The Data Strategist Internal in the Plugins Directory, install dbt Agents, and connect with an approved Google account. See Plugin distribution for team setup, validation, and the requirements that remain before a public submission. Brand Monitor uses a separate hosted connection; see Brand Monitor plugin distribution for its exact project boundary and teammate onboarding flow.

The hosted internal plugin exposes only bounded, read-only access to the approved dbt mart. The local toolkit retains its separate plan-and-approval workflow for dbt changes.

Related MCP server: bq-guard-mcp

Quick start

python3 -m venv .venv
.venv/bin/pip install -e '.[all,dev]'
cp examples/keylo.dbt-agents.yml dbt-agents.yml
.venv/bin/dbt-agents check-config --config dbt-agents.yml
.venv/bin/dbt-agents project keylo --config dbt-agents.yml

See Getting started for authentication, Codex, and ChatGPT setup. The architecture and acceptance criteria are in the design specification.

Project-scoped tools use the configured dbt-agents alias (for example, keylo), not the warehouse project ID. Use the read-only project_list MCP tool or dbt-agents projects CLI command to discover valid aliases. See the project discovery specification.

For a repository that has not yet been configured, use the initial CLI-first project onboarding and readiness flow. It discovers a dbt project's configuration contract, collects operator-confirmed non-secret values, validates from offline checks through optional bounded warehouse access, and only then registers an MCP project alias.

Before approving dbt execution, run the offline and live readiness checks in Operational readiness. The same guide covers non-mutating IAM verification, the validation ladder, and trusted release publishing.

Safety model

• strict repository roots and writable-path allowlists;

• protected credential and environment files;

• SHA-guarded atomic file replacement;

• SQL AST validation, one-statement enforcement, dry runs, byte budgets, row limits, and IAM read-only query credentials;

• exact short-lived plans plus out-of-band local approval for writes;

• separate query and dbt-runner identities;

• fixed dbt and Git command builders with no arbitrary shell tool; and

• sanitized, owner-only JSONL audit events without file bodies or query results.

The initial warehouse provider is BigQuery. Provider contracts are intentionally small so other adapters can implement the same safety semantics.

Compatibility

The public names, safety defaults, and v1 support boundary are frozen in the v1 contract and ADR-0001. Additive changes remain possible; breaking configuration or MCP changes require a new contract version and migration guide.

v1 supports Python 3.11–3.13, dbt Core 1.10–1.11, BigQuery, macOS/Linux local execution, and GitHub.com publishing through git and gh.