dbt MCP Server

# dbt MCP Server Quick Start Guide Get up and running with the dbt MCP server for Claude Code integration in 5 minutes. ## Prerequisites ✅ **Environment Setup** - Python 3.12+ with virtual environment - dbt Core 1.6.0+ installed - DuckDB database available - Claude Code installed and configured ✅ **Project Requirements** - Existing dbt project in `transform/` directory - DuckDB database with sample data - dbt profiles configured for DuckDB ## 5-Minute Setup ### Step 1: Install Dependencies (1 min) ```bash # Activate your virtual environment source venv/bin/activate # Install MCP dependencies pip install dbt-mcp mcp # Verify installation python -c "import mcp, dbt_mcp; print('✅ Dependencies installed')" ``` ### Step 2: Configure Environment (1 min) **Check Configuration File**: ```bash # Review .env.dbt-mcp (already created) cat .env.dbt-mcp ``` **Verify Paths**: ```bash # Ensure all required paths exist ls -la transform/ # dbt project ls -la data/warehouse/ # DuckDB database ls -la mcp_servers/ # MCP server code ``` ### Step 3: Test MCP Server (1 min) ```bash # Test server initialization source venv/bin/activate && source .env.dbt-mcp && python -c " import sys sys.path.insert(0, '.') from mcp_servers.dbt_server import DbtMCPServer server = DbtMCPServer() print('✅ MCP server initialized successfully') print(f'📊 Found {len(server._discover_models())} models') " ``` Expected output: ``` ✅ MCP server initialized successfully 📊 Found 3 models ``` ### Step 4: Start MCP Server (30 sec) ```bash # Start the dbt MCP server ./scripts/start_dbt_mcp.sh ``` Expected output: ``` 🚀 Starting dbt MCP Server for Claude Code... ✅ Loaded dbt MCP configuration 📊 dbt MCP Server Configuration: Project Dir: /path/to/transform Profile: data_stack Target: dev Database: /path/to/data_stack.duckdb 🎯 Starting MCP server... ``` **Note**: Server will run in foreground. Open new terminal for next steps. ### Step 5: Configure Claude Code (1.5 min) **Option A: Use provided configuration** ```bash # Copy Claude configuration cp mcp_servers/claude_config.json ~/.claude/claude_desktop_config.json # Update paths in the file (replace /Users/ajdoyle/claude-data-stack-mcp with your path) ``` **Option B: Add to existing Claude configuration** Add this to your existing `~/.claude/claude_desktop_config.json`: ```json { "mcpServers": { "dbt-data-stack": { "command": "python", "args": [ "/your/path/to/claude-data-stack-mcp/mcp_servers/dbt_server.py" ], "env": { "DBT_PROJECT_DIR": "/your/path/to/claude-data-stack-mcp/transform", "DBT_PROFILES_DIR": "/your/path/to/claude-data-stack-mcp/transform/profiles/duckdb", "DBT_PROFILE": "data_stack", "DBT_TARGET": "dev", "DUCKDB_PATH": "/your/path/to/claude-data-stack-mcp/data/warehouse/data_stack.duckdb" } } } } ``` ### Step 6: Test Integration (30 sec) **Restart Claude Code** and test with these prompts: ``` "Show me what dbt models are available in this project" "Run dbt tests to validate data quality" "Query the employee dimension table" ``` ## Verification Checklist ### ✅ Server Status ```bash # Check server is running ps aux | grep dbt_server.py # Test server response (in another terminal) python -c " import asyncio import sys sys.path.insert(0, '.') from mcp_servers.dbt_server import DbtMCPServer async def test(): server = DbtMCPServer() models = await server._discover_models() print(f'✅ Server responsive: {len(models)} models found') asyncio.run(test()) " ``` ### ✅ Claude Integration In Claude Code, you should see: - 🔧 MCP server connection established - 🎯 dbt tools available in tool selection - 📊 Intelligent responses to dbt-related queries ### ✅ Tool Availability Test each tool category: ``` # CLI Tools "Compile the staging model" → dbt_compile "Run employee models" → dbt_run "Test data quality" → dbt_test # Discovery Tools "List all models" → discovery_list_models "Show me model details" → discovery_model_details # Remote Tools "Query the database" → remote_query_database "Describe the employee table" → remote_describe_table ``` ## Quick Commands Reference ### Start/Stop Server ```bash # Start server (foreground) ./scripts/start_dbt_mcp.sh # Stop server Ctrl+C # Start server (background) nohup ./scripts/start_dbt_mcp.sh > mcp_server.log 2>&1 & # Check background server tail -f mcp_server.log ``` ### Common Operations ```bash # Test dbt project cd transform DBT_PROFILES_DIR=./profiles/duckdb dbt debug --profile data_stack # Run dbt pipeline meltano run tap-csv target-duckdb # ELT cd transform && DBT_PROFILES_DIR=./profiles/duckdb dbt run --profile data_stack # Transform # Query database directly python -c " import duckdb conn = duckdb.connect('data/warehouse/data_stack.duckdb') print(conn.execute('SHOW TABLES').fetchall()) " ``` ### Troubleshooting ```bash # Check environment source .env.dbt-mcp && env | grep DBT # Validate paths ls -la $DBT_PROJECT_DIR ls -la $DBT_PROFILES_DIR ls -la $DUCKDB_PATH # Test imports python -c "from mcp_servers.dbt_server import DbtMCPServer; print('✅ Import OK')" # Check logs tail -f mcp_server.log ``` ## Expected Claude Code Behaviors Once configured, Claude Code will provide intelligent dbt assistance: ### 🎯 Automatic Tool Selection - **"Run dbt models"** → Automatically uses `dbt_run` - **"What models exist?"** → Uses `discovery_list_models` - **"Show me data"** → Uses `remote_query_database` ### 🧠 Context-Aware Responses - Understands your dbt project structure - Provides model-specific recommendations - Suggests data quality improvements - Explains data transformations ### ⚡ Workflow Integration - Compiles before running problematic models - Tests after making changes - Explores data to answer questions - Provides troubleshooting guidance ## Next Steps ### 📚 Learn More - [API Reference](API_REFERENCE.md) - Complete tool documentation - [Usage Examples](USAGE_EXAMPLES.md) - Practical workflows - [MCP Integration Guide](MCP_INTEGRATION.md) - Detailed setup ### 🚀 Advanced Features - Enable semantic layer tools for advanced analytics - Set up automated testing workflows - Integrate with CI/CD pipelines - Add custom tool extensions ### 🔧 Customization - Modify tool configurations in `.env.dbt-mcp` - Add custom dbt commands - Extend database query capabilities - Implement project-specific workflows ## Success Indicators ✅ **You're ready when**: - MCP server starts without errors - Claude Code recognizes dbt tools - Basic dbt operations work through Claude - Database queries return expected results - Model discovery shows your dbt models 🎉 **Congratulations!** You now have intelligent dbt assistance through Claude Code via the MCP protocol. --- **Need Help?** - Check [Troubleshooting Guide](MCP_INTEGRATION.md#troubleshooting) - Review [Test Report](../tests/test_report.md) for validation - Examine server logs for error details