dbt-agent-layer

Make your dbt metrics queryable by AI agents via MCP.

pip install dbt-agent-layer
cd my_dbt_project
dbt-agent serve
# → MCP server running, connect Claude Desktop, ask questions grounded in real data

Quick start

# 1. Install
pip install "dbt-agent-layer[duckdb]"   # or [postgres], [bigquery], [snowflake]

# 2. Initialise (inside your dbt project)
cd my_dbt_project
dbt-agent init

# 3. Build tool registry
dbt-agent build

# 4. Start the MCP server
dbt-agent serve

How it works

dbt project on disk
       ↓
[Parser] reads manifest.json + schema.yml + metrics.yml
       ↓
[Generator] produces async Python tool functions per metric
       ↓
[MCP Server] registers tools, starts server
       ↓
MCP client (Claude Desktop, any agent) calls tool
       ↓
[Executor] runs SQL against your warehouse
       ↓
[Delta + Narrative] enriches raw number with context
       ↓
MetricResult returned to agent (value + delta + narrative + anomaly flag)

Supported warehouses

dbt version compatibility

Claude Desktop setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dbt-metrics": {
      "command": "dbt-agent",
      "args": ["serve", "--project-dir", "/path/to/your/dbt/project"],
      "env": {}
    }
  }
}

Restart Claude Desktop. You can now ask:

• "What's our MRR this month vs last month?"
• "Show me revenue broken down by channel for Q1 2024."
• "Is churn rate anomalous this month?"

Configuration reference (dbt-agent.yml)

version: 1

project:
  dir: "."                      # path to dbt project
  profiles_dir: "~/.dbt"        # path to profiles.yml
  target: "dev"                 # dbt target to use

adapter:
  type: postgres                # postgres | bigquery | snowflake | duckdb
  # Connection details pulled from profiles.yml automatically.
  # Override individual fields here if needed.

server:
  host: "0.0.0.0"
  port: 8000
  transport: "stdio"            # stdio (Claude Desktop) | http (web clients)

metrics:
  include: []                   # empty = all metrics
  exclude: []                   # metric names to hide from agents
  default_period: "current_month"
  compare_to: "prior_period"    # prior_period | prior_year

narratives:
  enabled: true
  style: "concise"              # concise | detailed

Environment variable overrides

CLI reference

dbt-agent init

Detect your dbt project, auto-detect the warehouse adapter, and create dbt-agent.yml.

dbt-agent init [--project-dir PATH] [--adapter postgres|bigquery|snowflake|duckdb]

dbt-agent build

Parse manifest.json, extract all metric definitions, write dbt_agent_tools/manifest_cache.json.

dbt-agent build [--project-dir PATH] [--skip-compile] [--dry-run] [--verbose]

dbt-agent serve

Start the MCP server with all metrics registered as callable tools.

dbt-agent serve [--project-dir PATH] [--port INT] [--transport stdio|http] [--skip-build] [--reload]

Built-in MCP tools (always available)

Each auto-generated tool returns a MetricResult containing:

• value + formatted_value (e.g. "$142,500")
• delta — period-over-period comparison
• narrative — factual one-sentence summary
• anomaly — statistical anomaly flag (>2σ from baseline)
• breakdown — dimension breakdown rows (if breakdown_by used)
• sql_executed — exact SQL run (for debugging)

Adding a new adapter

1. Create dbt_agent_layer/executor/mydb_exec.py implementing BaseExecutor:

   from .base import BaseExecutor
   
   class MyDBExecutor(BaseExecutor):
       async def execute(self, sql: str) -> list[dict]: ...
       async def test_connection(self) -> bool: ...
       def get_adapter_type(self) -> str: return "mydb"
   

2. Add a case to executor/factory.py:get_executor().
3. Add optional dependency to pyproject.toml.
4. Open a PR — contributions welcome!

Development

git clone https://github.com/dbt-agent-layer/dbt-agent-layer
cd dbt-agent-layer
pip install -e ".[dev,duckdb]"
pytest
ruff check .
mypy dbt_agent_layer/

License

Apache 2.0 — see LICENSE.

Roadmap

• v0.2: Result caching, dbt Cloud artifact API, web UI
• Cloud tier: Team collaboration, audit logs, SSO