dbt-cloud-migrate

A CLI tool and MCP server that audits dbt Core projects and generates actionable guidance for migrating to dbt Cloud. Designed to work alongside the official dbt MCP server.

How it fits with the dbt MCP server

The typical workflow is:

1. Run check_project or check_deprecations to find migration issues

2. Run fix_deprecations to auto-fix safe changes

3. Use the dbt MCP server's compile or build tools to confirm the project still works

Related MCP server: openclaw-upgrade-orchestrator-mcp

What it checks

• Profiles migration — analyzes profiles.yml, maps adapter types to dbt Cloud connection types, flags hardcoded credentials, and generates recommended DBT_ENV_SECRET_ environment variable mappings

• Project structure — checks model layer organization (staging/intermediate/marts), naming conventions (stg_, int_, fct_, dim_), source YAML definitions, documentation coverage, primary key test coverage, and .gitignore settings

• Deprecated syntax — detects renamed dbt_project.yml keys, legacy tests: YAML keys, deprecated dbt_utils macros, env_var() calls without defaults, hardcoded target.name references, hardcoded 3-part database references, and unpinned packages

Each issue includes a severity level (ERROR, WARNING, INFO) and a concrete fix recommendation.

Installation

Requires Python 3.10+.

git clone <repo>
cd dbt-refactoring-tool
python3 -m venv .venv
.venv/bin/pip install -e .

MCP Server Setup

Prerequisites

Install uv for the dbt MCP server:

curl -LsSf https://astral.sh/uv/install.sh | sh

Claude Code — add both servers

# Official dbt MCP server
claude mcp add dbt -s user -- uvx dbt-mcp

# Migration audit server (this tool)
claude mcp add dbt-cloud-migrate -s user -- dbt-cloud-migrate-mcp

Set your project path for the dbt MCP server — edit ~/.claude.json and add env vars:

{
  "mcpServers": {
    "dbt": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/dbt"
      }
    },
    "dbt-cloud-migrate": {
      "type": "stdio",
      "command": "dbt-cloud-migrate-mcp"
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/dbt"
      }
    },
    "dbt-cloud-migrate": {
      "command": "dbt-cloud-migrate-mcp"
    }
  }
}

Available MCP tools

dbt-cloud-migrate tools (this server):

dbt MCP server tools (complement these with):

CLI Usage

Run all checks

dbt-cloud-migrate check /path/to/your/dbt/project

Run from your project root:

cd ~/projects/my_dbt_project
dbt-cloud-migrate check .

Output formats

# Rich terminal output (default)
dbt-cloud-migrate check . --output rich

# JSON — useful for CI or piping to other tools
dbt-cloud-migrate check . --output json

# Compact summary table
dbt-cloud-migrate check . --output summary

Run specific checks only

dbt-cloud-migrate check . --only profiles
dbt-cloud-migrate check . --only deprecations
dbt-cloud-migrate check . --only profiles,deprecations

Available check names: profiles, structure, deprecations

Profiles-only command

dbt-cloud-migrate profiles /path/to/project

Auto-fix deprecated syntax

Fix renamed dbt_project.yml keys and tests: → data_tests: in schema YAML files:

# Preview changes without modifying files
dbt-cloud-migrate fix . --dry-run

# Apply fixes
dbt-cloud-migrate fix .

After fixing, validate with the dbt MCP server or CLI:

dbt compile

Version

dbt-cloud-migrate version

Checks reference

Profiles migration

• Adapter → dbt Cloud connection type mapping (Snowflake, BigQuery, Databricks, Redshift, Postgres, and more)

• Hardcoded sensitive fields (password, token, private_key, etc.) that should use env_var()

• Recommended DBT_ENV_SECRET_ variable names per adapter

• Multiple targets → separate dbt Cloud Environments guidance

• profiles.yml committed to the project directory (security risk)

Project structure

• profiles.yml inside the project repo

• Missing or incomplete .gitignore (target/, dbt_packages/, profiles.yml, logs/)

• Missing dbt_project.yml or required keys (name, version, profile)

• SQL models in the root models/ directory (not organized into layers)

• Missing standard layer folders (staging/, intermediate/, marts/)

• Naming convention violations (stg_ in staging, int_ in intermediate, fct_/dim_ in marts)

• No source YAML files in models/staging/

• Models with no schema YAML entry or empty description

• Primary key columns (id, *_id, *_key, *_pk) missing unique + not_null tests

Deprecated syntax

• Renamed dbt_project.yml keys: source-paths → model-paths, data-paths → seed-paths, modules-path → packages-install-path

• config-version: 2 no longer required (dbt 1.5+)

• Legacy tests: key in schema YAML (should be data_tests: in dbt 1.8+)

• version: 2 in schema YAML files (no longer required in dbt 1.5+)

• Unpinned Hub packages (no version) and unpinned Git packages (no revision)

• Deprecated dbt_utils macros moved to dbt core (dbt_utils.surrogate_key, dbt_utils.current_timestamp, type macros, date macros)

• env_var() calls without a default value (will fail in Cloud if variable is unset)

• {{ target.name }} usage (recommend environment variable approach in Cloud)

• Hardcoded 3-part database.schema.table references in SQL (should use ref() or source())

Exit codes

• 0 — all checks passed

• 1 — one or more ERROR or WARNING issues found

This makes dbt-cloud-migrate check suitable for use in CI pipelines.