Настройка локального MCP

Локальный сервер dbt MCP запускается на вашей машине и поддерживает dbt Core, dbt Fusion Engine и Cloud CLI. Вы можете использовать его как с учетной записью dbt platform, так и без неё.

Предварительные требования

• Установите uv, чтобы иметь возможность запускать dbt-mcp и связанные зависимости в изолированном виртуальном окружении.
• Иметь локальный проект dbt (если вы хотите использовать команды dbt CLI).

Варианты настройки

Выберите способ настройки, который лучше всего подходит под ваш рабочий процесс:

OAuth-аутентификация с dbt platform EnterpriseEnterprise +

Этот метод использует OAuth для аутентификации в вашей учетной записи dbt platform. Это самый простой вариант настройки, который не требует ручного управления токенами или переменными окружения.

Требуются статические поддомены

Только учетные записи со статическими поддоменами (например, abc123.us1.dbt.com) могут использовать OAuth с MCP-серверами. Все учетные записи находятся в процессе миграции на статические поддомены до декабря 2025 года. Для получения дополнительной информации обратитесь в службу поддержки.

Параметры конфигурации

dbt platform only

Этот вариант предназначен для пользователей, которым нужны только возможности dbt platform (Discovery API, Semantic Layer, управление заданиями) без использования локальных CLI‑команд.

Если вы используете только dbt platform, инструменты CLI автоматически отключаются. Значение поля DBT_HOST можно найти в информации о вашей учетной записи dbt platform в разделе Access URLs.

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "https://<your-dbt-host-with-custom-subdomain>",
      }
    }
  }
}

Примечание: Замените <your-dbt-host-with-custom-subdomain> на ваш реальный хост (например, abc123.us1.dbt.com). Это включает аутентификацию OAuth без необходимости локальной установки dbt.

dbt platform + CLI

Этот вариант предназначен для пользователей, которым нужны как команды dbt CLI, так и возможности dbt platform (Discovery API, Semantic Layer, управление заданиями).

Для доступа к CLI обязательны поля DBT_PROJECT_DIR и DBT_PATH. Значение поля DBT_HOST можно найти в информации о вашей учетной записи dbt platform в разделе Access URLs.

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "https://<your-dbt-host-with-custom-subdomain>",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt/executable"
      }
    }
  }
}

Примечание: Замените <your-dbt-host-with-custom-subdomain> на ваш реальный хост (например, https://abc123.us1.dbt.com). Это включает аутентификацию OAuth.

После настройки ваша сессия подключается к учетной записи dbt platform, запускает процесс OAuth-аутентификации, а затем открывает вашу учетную запись, где вы можете выбрать проект, на который хотите ссылаться.

Выбор проекта dbt platform

После завершения настройки OAuth перейдите к разделу Проверка конфигурации.

Только CLI (без dbt platform)

Если вы используете CLI dbt Core или Fusion и вам не нужен доступ к возможностям dbt platform (Discovery API, Semantic Layer, Administrative API), вы можете настроить локальный MCP, указав только информацию о вашем проекте dbt.

Добавьте следующую конфигурацию в ваш MCP-клиент (точное расположение файлов см. в соответствующих руководствах по интеграции):

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

Определение путей

Следуйте инструкциям для вашей ОС, чтобы определить нужные пути:

 macOS/Linux

• DBT_PROJECT_DIR: Полный путь к папке с вашим проектом dbt

  • Пример: /Users/yourname/dbt-projects/my_project
  • Это папка, содержащая файл dbt_project.yml.

• DBT_PATH: Найдите путь к исполняемому файлу dbt, выполнив в терминале:

  which dbt
  • Пример вывода: /opt/homebrew/bin/dbt
  • Используйте именно этот путь в конфигурации.

 Windows

• DBT_PROJECT_DIR: Полный путь к папке с вашим проектом dbt

  • Пример: C:\Users\yourname\dbt-projects\my_project
  • Это папка, содержащая файл dbt_project.yml.
  • Используйте прямые слеши или экранированные обратные слеши: C:/Users/yourname/dbt-projects/my_project

• DBT_PATH: Найдите путь к исполняемому файлу dbt, выполнив команду в Command Prompt или PowerShell:

  where dbt
  • Пример вывода: C:\Python39\Scripts\dbt.exe
  • Используйте прямые слеши или экранированные обратные слеши: C:/Python39/Scripts/dbt.exe

После завершения этой настройки перейдите к разделу Проверка конфигурации.

Настройка через переменные окружения

Если вам нужно настроить несколько переменных окружения или вы предпочитаете управлять ими отдельно, вы можете использовать переменные окружения. Если вы используете только команды dbt CLI, вам не нужно указывать переменные окружения, специфичные для dbt platform, и наоборот.

Пример файла:

DBT_HOST=cloud.getdbt.com
DBT_PROD_ENV_ID=your-production-environment-id
DBT_DEV_ENV_ID=your-development-environment-id
DBT_USER_ID=your-user-id
DBT_ACCOUNT_ID=your-account-id
DBT_TOKEN=your-service-token
DBT_PROJECT_DIR=/path/to/your/dbt/project
DBT_PATH=/path/to/your/dbt/executable
MULTICELL_ACCOUNT_PREFIX=your-account-prefix

Этот файл потребуется для интеграции с инструментами, совместимыми с MCP.

Настройки API и SQL-инструментов

Переменная окружения	Обязательна	Описание
DBT_HOST	Обязательна	Имя хоста вашего инстанса dbt platform. Важно: для Multi-cell учетных записей не включайте префикс учетной записи в hostname. Значение по умолчанию — cloud.getdbt.com.
MULTICELL_ACCOUNT_PREFIX	Требуется только для Multi-cell инстансов	Укажите здесь префикс вашей Multi-cell учетной записи (не в DBT_HOST). Если вы не используете Multi-cell, не задавайте это значение. Подробнее о регионах и хостинге см. здесь.
DBT_TOKEN	Обязательна	Ваш персональный access token или service token из dbt platform. Примечание: при использовании Semantic Layer рекомендуется использовать персональный access token. Если вы используете service token, убедитесь, что у него есть как минимум разрешения Semantic Layer Only, Metadata Only и Developer.
DBT_ACCOUNT_ID	Требуется для инструментов Administrative API	Ваш ID учетной записи dbt
DBT_PROD_ENV_ID	Обязательна	ID production-окружения dbt platform
DBT_DEV_ENV_ID	Необязательна	ID development-окружения dbt platform
DBT_USER_ID	Необязательна	Ваш user ID в dbt platform (документация)

Loading table...

Примеры конфигурации Multi-cell:

✅ Корректная конфигурация:

DBT_HOST=us1.dbt.com
MULTICELL_ACCOUNT_PREFIX=abc123

❌ Некорректная конфигурация (распространённая ошибка):

DBT_HOST=abc123.us1.dbt.com  # Не включайте префикс в host!
# MULTICELL_ACCOUNT_PREFIX не задан

Если ваш полный URL — abc123.us1.dbt.com, разделите его так:

• DBT_HOST=us1.dbt.com
• MULTICELL_ACCOUNT_PREFIX=abc123

Настройки dbt CLI

Локальный dbt-mcp поддерживает все варианты dbt, включая dbt Core и dbt Fusion Engine.

Переменная окружения	Обязательна	Описание	Пример
DBT_PROJECT_DIR	Обязательна	Полный путь к локальному репозиторию вашего проекта dbt. Это папка, содержащая файл dbt_project.yml.	macOS/Linux: /Users/myname/reponame Windows: C:/Users/myname/reponame
DBT_PATH	Обязательна	Полный путь к исполняемому файлу dbt (dbt Core/Fusion/Cloud CLI). См. следующий раздел для поиска этого пути.	macOS/Linux: /opt/homebrew/bin/dbt Windows: C:/Python39/Scripts/dbt.exe
DBT_CLI_TIMEOUT	Необязательна	Количество секунд до тайм-аута выполнения команд dbt CLI агентом.	По умолчанию 60 секунд.

Loading table...

Определение DBT_PATH

Следуйте инструкциям для вашей ОС, чтобы найти DBT_PATH:

 macOS/Linux

Выполните команду в терминале:

which dbt

Пример вывода: /opt/homebrew/bin/dbt

 Windows

Выполните команду в Command Prompt или PowerShell:

where dbt

Пример вывода: C:\Python39\Scripts\dbt.exe

Примечание: используйте прямые слеши в конфигурации: C:/Python39/Scripts/dbt.exe

Дополнительные примечания:

• Вы можете задавать любые переменные окружения, поддерживаемые вашим исполняемым файлом dbt, например поддерживаемые в dbt Core.
• dbt MCP учитывает стандартные переменные окружения и флаги для сбора статистики использования, описанные здесь.
• DBT_WARN_ERROR_OPTIONS='{"error": ["NoNodesForSelectionCriteria"]}' устанавливается автоматически, чтобы MCP-сервер понимал, что при выполнении команды dbt не был выбран ни один узел. При необходимости вы можете переопределить это значение, однако оно обеспечивает более удобную работу при вызове dbt из MCP-сервера, гарантируя выбор корректных узлов.

Отключение инструментов

Вы можете отключить следующий доступ к инструментам в локальном dbt-mcp:

Название	По умолчанию	Описание
DISABLE_DBT_CLI	false	Установите true, чтобы отключить MCP-инструменты dbt Core, Cloud CLI и dbt Fusion.
DISABLE_SEMANTIC_LAYER	false	Установите true, чтобы отключить MCP-инструменты dbt Semantic Layer.
DISABLE_DISCOVERY	false	Установите true, чтобы отключить MCP-инструменты dbt Discovery API.
DISABLE_ADMIN_API	false	Установите true, чтобы отключить MCP-инструменты dbt Administrative API.
DISABLE_SQL	true	Установите false, чтобы включить SQL MCP-инструменты.
DISABLE_DBT_CODEGEN	true	Установите false, чтобы включить MCP-инструменты dbt codegen (требуется пакет dbt-codegen).
DISABLE_TOOLS	""	Укажите список имён инструментов, разделённых ,, чтобы отключить конкретные инструменты.

Loading table...

Использование переменных окружения в конфигурации MCP-клиента

Рекомендуемый способ настройки MCP-клиента — использовать поле env в вашем JSON-файле конфигурации. Это позволяет хранить всю конфигурацию в одном файле:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "your-token-here",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt"
      }
    }
  }
}

Использование файла .env

Если вы предпочитаете управлять переменными окружения в отдельном файле, вы можете создать файл .env и сослаться на него:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["--env-file", "/path/to/.env", "dbt-mcp"]
    }
  }
}

Однако этот подход требует управления двумя файлами вместо одного.

(Необязательно) Проверка конфигурации

В командной строке выполните следующее, чтобы проверить настройку:

Если используется поле env в JSON:

export DBT_PROJECT_DIR=/path/to/project
export DBT_PATH=/path/to/dbt
uvx dbt-mcp

Если используется файл .env:

uvx --env-file <path-to-.env-file> dbt-mcp

Если ошибок нет, значит конфигурация настроена корректно.

Настройка MCP-клиента

После завершения конфигурации следуйте соответствующему руководству по интеграции для выбранного инструмента:

• Claude
• Cursor
• VS Code

Отладочные настройки

Эти параметры позволяют настроить уровень логирования MCP-сервера для диагностики и устранения проблем.

Название	По умолчанию	Описание
DBT_MCP_LOG_LEVEL	INFO	Переменная окружения для переопределения уровня логирования MCP-сервера. Возможные значения: DEBUG, INFO, WARNING, ERROR, CRITICAL.

Loading table...

Чтобы увидеть больше деталей о работе MCP-сервера и упростить отладку, вы можете временно установить уровень логирования DEBUG. Рекомендуется использовать его временно, чтобы избежать переполнения диска логами.

Устранение неполадок

Не удаётся найти исполняемый файл uvx

Некоторые MCP-клиенты могут не находить uvx из JSON-конфигурации. Это приводит к ошибкам вида Could not connect to MCP server dbt-mcp, Error: spawn uvx ENOENT и подобным.

Решение: найдите полный путь к uvx и укажите его в конфигурации:

• macOS/Linux: выполните which uvx в терминале.
• Windows: выполните where uvx в CMD или PowerShell.

Затем обновите JSON-конфигурацию, указав полный путь:

{
  "mcpServers": {
    "dbt": {
      "command": "/full/path/to/uvx", # Например, на macOS с Homebrew: "command": "/opt/homebrew/bin/uvx"
      "args": ["dbt-mcp"],
      "env": { ... }
    }
  }
}

Нашли ошибку?

Создать GitHub Issue