MCP Server Integration

dbt-toolbox provides an MCP (Model Context Protocol) server implementation, enabling integration with AI assistants and external tools. This allows you to leverage dbt-toolbox's intelligent caching, dependency analysis, and validation capabilities from within other applications.

🚀 Quick Start

Installation

# Install dbt-toolbox with MCP support
uv add "dbt-toolbox[mcp]"

# Or with pip
pip install "dbt-toolbox[mcp]"

Claude CLI

Set it up in claude by running:

claude mcp add dbt-toolbox -- uv run dt start-mcp-server

VSCode Copilot

Set it up in Copilot by adding the following to your .vscode/mcp.json and click "start":

{
    "servers": {
        "dbt-toolbox": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "run",
                "dt",
                "start-mcp-server",
            ]
        }
    }
}

Basic Usage

The MCP server exposes dbt-toolbox functionality through standardized MCP tools that can be called by MCP clients like Claude Code, Copilot, and other AI development tools.

# The server is accessible via the FastMCP app
# Location: dbt_toolbox.mcp.mcp:app

🛠️ Available Tools

analyze_models()

Validates all model references, column references, and CTE references in your dbt project.

Purpose: Ensures data lineage integrity and catches broken references before execution.

Returns: JSON object with validation results

Key Features:

• Validates column existence across model dependencies
• Checks CTE reference integrity
• Identifies non-existent table references
• Respects validation ignore lists from configuration

build_models()

Executes dbt build with intelligent cache-based execution and enhanced capabilities.

Parameters:

• model (str, optional): Select models to build (dbt selection syntax)
• full_refresh (bool, default=False): Drop incremental models and rebuild
• threads (int, optional): Number of threads to use
• vars (str, optional): Supply variables to the project (YAML string)
• target (str, optional): Specify dbt target environment
• analyze_only (bool, default=False): Only analyze which models need execution
• disable_smart (bool, default=False): Disable intelligent execution

Returns: JSON object with execution results and performance metrics

Smart Execution Features:

• Cache Analysis: Only rebuilds models with outdated cache or dependency changes
• Lineage Validation: Validates column and model references before execution
• Performance Tracking: Reports time saved by skipping unnecessary model executions
• Optimized Selection: Automatically filters to models that need execution

🔧 Configuration

The MCP server respects the same configuration system as the CLI commands:

Configuration Sources (by precedence):

1. Environment Variables (highest priority)
2. TOML Configuration (pyproject.toml)
3. dbt Profiles (for SQL dialect and connection)
4. Auto-detection (for project paths)
5. Defaults (lowest priority)

Key Settings for MCP Usage

[tool.dbt_toolbox]
# Core settings
dbt_project_dir = "path/to/your/dbt/project"
cache_path = ".dbt_toolbox"
cache_validity_minutes = 1440  # 24 hours

# Validation settings
enforce_lineage_validation = true
models_ignore_validation = ["legacy_model", "temp_model"]

# Performance settings  
debug = false

Environment Variables

# Project configuration
export DBT_PROJECT_DIR="/path/to/dbt/project"
export DBT_PROFILES_DIR="/path/to/profiles"

# dbt-toolbox specific
export DBT_TOOLBOX_ENFORCE_LINEAGE_VALIDATION=true
export DBT_TOOLBOX_MODELS_IGNORE_VALIDATION="legacy_model,temp_model"
export DBT_TOOLBOX_CACHE_VALIDITY_MINUTES=1440
export DBT_TOOLBOX_DEBUG=false

🏗️ Integration Patterns

AI Assistant Integration

Perfect for AI-powered dbt development workflows:

1. Pre-execution Validation: Always run analyze_models() before making changes
2. Intelligent Builds: Use build_models() with smart execution for faster iterations
3. Impact Analysis: Use selection syntax like +model+ to understand dependencies
4. Performance Monitoring: Track skipped models and time savings

Development Tools Integration

Enable dbt-toolbox in your development environment:

1. IDE Extensions: MCP-compatible editors can call tools directly
2. CLI Wrappers: Create custom scripts that leverage MCP tools
3. Notebooks: Use MCP tools in Jupyter notebooks for exploratory analysis

🔍 Troubleshooting

Common Issues

Connection Errors:

• Ensure dbt profiles are configured correctly
• Check DBT_PROFILES_DIR environment variable
• Verify target exists in profiles.yml

Validation Failures:

• Review models listed in validation results
• Add problematic models to models_ignore_validation
• Check for missing sources or macros

Performance Issues:

• Increase cache_validity_minutes for longer cache retention
• Use targeted model selection instead of full project builds
• Check debug=true to understand cache behavior

📊 Benefits

Development Efficiency

• Faster Iterations: Smart caching eliminates unnecessary model rebuilds
• Early Error Detection: Validation catches issues before expensive builds
• Performance Insights: Clear metrics on time saved and models skipped

Code Quality

• Lineage Validation: Ensures data integrity across model dependencies
• Reference Checking: Catches broken table and column references
• CTE Validation: Validates complex SQL patterns and Common Table Expressions

Integration Flexibility

• Standardized Protocol: MCP enables consistent tool integration
• AI-Powered Workflows: Perfect for AI assistant development patterns
• Configuration Consistency: Same settings as CLI commands

🤝 Contributing

The MCP server is part of the main dbt-toolbox codebase. See the main Contributing Guide for development setup and guidelines.

MCP-Specific Development

When working on MCP functionality:

1. Consistency: Ensure MCP tools provide same functionality as CLI commands
2. Error Handling: Return structured JSON responses for all scenarios
3. Documentation: Keep tool docstrings comprehensive for AI assistants
4. Testing: Test both CLI and MCP interfaces for feature parity

📚 Additional Resources

• Model Context Protocol Specification
• FastMCP Documentation
• dbt-toolbox CLI Reference
• Main Documentation