Настройка MCP на собственной инфраструктуре

Локальный MCP-сервер dbt работает на вашем компьютере и поддерживает dbt v1, dbt v2 и dbt platform CLI. Его можно использовать как с учетной записью dbt platform, так и без нее.

Клонирование не требуется

Для использования локального MCP-сервера не нужно клонировать репозиторий dbt-mcp. Установите uv и выполните uvx dbt-mcp — эта команда загрузит и запустит dbt-mcp.

Если вы хотите внести свой вклад в dbt MCP, клонируйте репозиторий dbt-mcp и присоединяйтесь к разработке!

Краткий обзор требований к инструментам

В этой таблице указано, что требуется каждому набору инструментов и может ли он работать с учетной записью dbt platform или без нее:

Набор инструментов	Обязательные переменные	Работает с учетной записью dbt platform	Работает без учетной записи dbt platform
dbt CLI	DBT_PROJECT_DIR, DBT_PATH	Да	Да
Semantic Layer	DBT_HOST, DBT_TOKEN, DBT_PROD_ENV_ID	Да	Нет
Discovery API	DBT_HOST, DBT_TOKEN, DBT_PROD_ENV_ID	Да	Нет
Admin API	DBT_HOST, DBT_TOKEN, DBT_ACCOUNT_ID	Да	Нет
Выполнение SQL (execute_sql)	Персональный токен доступа, DBT_DEV_ENV_ID, DBT_USER_ID	Да	Нет
Codegen	DBT_PROJECT_DIR, DBT_PATH и DISABLE_DBT_CODEGEN=false	Да	Да
LSP / dbt v2	DBT_PROJECT_DIR, DBT_PATH и расширение dbt для VS Code	Да	Да

Наборы инструментов автоматически отключаются при отсутствии обязательных переменных

Если обязательная переменная не задана, dbt-mcp автоматически отключит соответствующий набор инструментов, а не выдаст ошибку. Например, если DBT_HOST не настроена, наборы инструментов Semantic Layer, Discovery и Admin API будут недоступны. Чтобы проверить, какие наборы инструментов активны, задайте DBT_MCP_LOG_LEVEL=DEBUG в своей среде и проверьте журналы сервера.

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

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

Выберите способ аутентификации

Если вы подключаетесь к функциям dbt platform (Semantic Layer, Discovery API, Admin API или выполнение SQL), вам необходимо пройти аутентификацию. Используйте эту таблицу, чтобы выбрать подходящий способ:

Если вам нужно...	Используйте...
Максимально быстрая первоначальная настройка	OAuth
Инструмент execute_sql	Персональный токен доступа (PAT). Сервисные токены не работают с execute_sql
Общая настройка или настройка для команды	Сервисный токен
CI или автоматизация	Сервисный токен

Для execute_sql требуется PAT

Инструмент execute_sql не работает с сервисными токенами. При использовании этого инструмента необходимо указать персональный токен доступа (PAT) в качестве значения DBT_TOKEN.

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

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

Аутентификация OAuth на платформе dbt StarterEnterpriseEnterprise +

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

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

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

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

dbt platform only

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

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

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_HOST": "YOUR-ACCESS-URL"
      }
    }
  }
}

Сообщить об ошибке в коде

Примечание: Замените YOUR-ACCESS-URL на имя хоста из вашего Access URL (например, abc123.us1.dbt.com). Допускаются оба варианта: abc123.us1.dbt.com и https://abc123.us1.dbt.com. Это позволяет использовать аутентификацию OAuth без необходимости самостоятельно размещать dbt.

dbt platform + CLI

Этот вариант предназначен для пользователей, которым нужны как команды dbt platform CLI, так и возможности платформы dbt (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": "YOUR-ACCESS-URL",
        "DBT_PROJECT_DIR": "/path/to/project",
        "DBT_PATH": "/path/to/dbt/executable"
      }
    }
  }
}

Сообщить об ошибке в коде

Примечание: Замените YOUR-ACCESS-URL именем хоста из вашего Access URL (например, abc123.us1.dbt.com). Допускаются оба варианта: abc123.us1.dbt.com и https://abc123.us1.dbt.com. Это позволяет использовать аутентификацию OAuth.

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

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

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

Только CLI (без платформы dbt)

Этот вариант запускает MCP-сервер локально и подключает его к вашему локальному проекту dbt с помощью DBT_PROJECT_DIR и DBT_PATH.

Если вы используете dbt v1 или dbt v2 и вам не нужен доступ к возможностям 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

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

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

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

Где разместить файл .env

Создайте файл .env в корневом каталоге проекта dbt (в той же папке, что и dbt_project.yml). При указании файла с помощью --env-file всегда используйте абсолютный путь, чтобы ваш MCP-клиент мог надежно его найти. Например, /absolute/path/to/your-dbt-project/.env.

Выберите пример .env, соответствующий вашей конфигурации. Включайте только необходимые переменные:

Только CLI

Используйте этот вариант, если вы выполняете команды dbt локально и вам не нужны функции dbt platform (Discovery API, Semantic Layer и т. д.):

DBT_PROJECT_DIR=/path/to/your/dbt/project
DBT_PATH=/path/to/your/dbt/executable

Сообщить об ошибке в коде

Только dbt platform

Используйте этот вариант, если вам нужны только функции dbt platform и вы не будете выполнять команды dbt:

DBT_HOST=cloud.getdbt.com
DBT_TOKEN=dbtc_your_token
DBT_PROD_ENV_ID=12345

Сообщить об ошибке в коде

CLI и dbt platform (самый распространенный вариант)

Используйте этот вариант, если вам нужны и команды dbt CLI, и функции dbt platform:

DBT_PROJECT_DIR=/path/to/your/dbt/project
DBT_PATH=/path/to/your/dbt/executable
DBT_HOST=cloud.getdbt.com
DBT_TOKEN=dbtc_your_token
DBT_PROD_ENV_ID=12345

Сообщить об ошибке в коде

Все переменные

Полный справочник всех доступных переменных. Для большинства конфигураций нужна лишь часть из них — подробные сведения о каждой переменной см. в таблицах Настройки инструментов API и SQL и Настройки dbt CLI.

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

Сообщить об ошибке в коде

Как передать переменные окружения в dbt-mcp

Ниже приведены несколько способов передачи переменных окружения. Для большинства конфигураций мы рекомендуем использовать файл .env с параметром --env-file:

Файл .env с параметром `--env-file`

1. Файл .env с параметром --env-file (рекомендуется) (обязательно укажите абсолютный путь в args):

Укажите абсолютный путь к файлу в конфигурации MCP-клиента:

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

Сообщить об ошибке в коде

Замените /absolute/path/to/your-dbt-project полным путём к папке, содержащей ваш файл dbt_project.yml.

Непосредственно в конфигурации MCP-клиента

2. Непосредственно в конфигурации MCP-клиента:

Передайте переменные непосредственно в поле env, заменив значения своими фактическими значениями. Это позволяет хранить всё в одном файле, но при этом токены будут храниться в конфигурации клиента:

{
  "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"
      }
    }
  }
}

Сообщить об ошибке в коде

Переменные окружения оболочки

3. Переменные окружения оболочки

Экспортируйте переменные в терминале перед запуском MCP-клиента, заменив значения своими фактическими значениями:

export DBT_HOST=cloud.getdbt.com
export DBT_TOKEN=your-token-here
export DBT_PROJECT_DIR=/path/to/project
uvx dbt-mcp

Сообщить об ошибке в коде

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

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

Переменная окружения	Обязательность	Описание
DBT_HOST	Обязательно	Имя хоста вашего экземпляра dbt platform. Значение по умолчанию — cloud.getdbt.com. Для учетных записей multi-cell и multi-tenant со статическим поддоменом используйте полное имя хоста, например abc123.us1.dbt.com.
DBT_TOKEN	Обязательно	Ваш персональный токен доступа или сервисный токен dbt platform. Примечание: если вы используете сервисный токен, назначьте наборы разрешений для включаемых наборов инструментов: Semantic Layer Only для инструментов Semantic Layer и Metadata Only для инструментов Discovery. Сервер, развернутый в собственной инфраструктуре, не проверяет разрешения при запуске. Вместо этого каждый API проверяет права доступа токена, когда инструмент обращается к нему. Токен, предоставляющий доступ только к некоторым наборам инструментов, работает для этих наборов, а вызовы инструментов из остальных наборов завершаются ошибкой по отдельности. Удаленный MCP-сервер также проверяет разрешения при каждом вызове инструмента в дополнение к проверкам при подключении. Инструмент execute_sql требует персональный токен доступа (PAT) и не работает с сервисными токенами. Мы также рекомендуем использовать PAT для инструментов Semantic Layer.
DBT_ACCOUNT_ID	Обязательно для инструментов Administrative API и аутентификации с помощью PAT	Ваш идентификатор учетной записи dbt. Также требуется, если в качестве DBT_TOKEN используется персональный токен доступа (PAT).
DBT_PROD_ENV_ID	Обязательно	Идентификатор вашей производственной среды dbt platform
DBT_DEV_ENV_ID	Необязательно	Идентификатор вашей среды разработки dbt platform
DBT_USER_ID	Необязательно	Ваш идентификатор пользователя dbt platform (документация)

Используйте только значения, а не полные URL-адреса

Распространенная ошибка — вставка полного URL-адреса вместо значения. Эти переменные принимают имена хостов или числовые идентификаторы:

# ✅ Правильно
DBT_HOST=cloud.getdbt.com            # https://cloud.getdbt.com тоже работает
DBT_PROD_ENV_ID=54321
DBT_USER_ID=123

# ❌ Неправильно — идентификаторы должны быть числами, а не полными URL-адресами
DBT_PROD_ENV_ID=https://cloud.getdbt.com/deploy/12345/projects/67890/environments/54321
DBT_USER_ID=https://cloud.getdbt.com/settings/profile

Сообщить об ошибке в коде

Пример конфигурации префикса поддомена:

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

DBT_HOST=abc123.us1.dbt.com  # Use the full hostname including the prefix
DBT_ACCOUNT_ID=12345          # Required when using PAT-based auth

Сообщить об ошибке в коде

Вам не нужно задавать MULTICELL_ACCOUNT_PREFIX или DBT_HOST_PREFIX.

Переменные окружения

Самостоятельно размещённый dbt-mcp поддерживает все варианты dbt, включая dbt v1 и dbt v2.

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

Определение 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 v1.
• dbt MCP учитывает стандартные переменные окружения и флаги для отслеживания использования, описанные здесь.
• DBT_WARN_ERROR_OPTIONS='{"error": ["NoNodesForSelectionCriteria"]}' задаётся автоматически, чтобы сервер MCP мог определить, что при выполнении команды dbt не выбран ни один узел. При необходимости вы можете переопределить это значение, но оно упрощает работу с dbt через сервер MCP, обеспечивая выбор допустимых узлов инструментом.

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

В dbt-mcp есть два режима управления доступностью инструментов. Выберите один из подходов:

• режим отключения (отключите то, что вам не нужно)
• режим включения (включите только то, что вам нужно)

Какой режим выбрать?

• Режим отключения — используйте, если вам нужна большая часть инструментов и требуется отключить лишь несколько из них. Это поведение по умолчанию.
• Режим включения — используйте, если вам нужен только небольшой набор инструментов (подход на основе списка разрешённых инструментов).

Не смешивайте оба режима для одного и того же набора инструментов. Например, не задавайте одновременно DISABLE_SEMANTIC_LAYER=true и DBT_MCP_ENABLE_SEMANTIC_LAYER=true — это может привести к непредсказуемому поведению.

Режим отключения (по умолчанию)

По умолчанию доступны все инструменты. Установите для нужной переменной значение true, чтобы отключить соответствующий набор:

Имя	Значение по умолчанию	Описание
DISABLE_DBT_CLI	false	Отключает MCP-инструменты dbt v1, dbt platform CLI и dbt v2.
DISABLE_SEMANTIC_LAYER	false	Отключает MCP-инструменты dbt Semantic Layer.
DISABLE_DISCOVERY	false	Отключает MCP-инструменты dbt Discovery API.
DISABLE_ADMIN_API	false	Отключает MCP-инструменты dbt Administrative API.
DISABLE_SQL	true	MCP-инструменты SQL отключены по умолчанию. Чтобы включить их, установите значение false.
DISABLE_DBT_CODEGEN	true	MCP-инструменты dbt codegen отключены по умолчанию. Чтобы включить их, установите значение false (требуется пакет dbt-codegen).
DISABLE_LSP	false	Отключает MCP-инструменты dbt LSP/dbt v2.
DISABLE_MCP_SERVER_METADATA	true	Инструменты метаданных MCP-сервера (например, get_mcp_server_version) отключены по умолчанию. Чтобы включить их, установите значение false.
DISABLE_TOOLS	""	Список имён конкретных инструментов, которые нужно отключить, разделённых запятыми.

Режим включения

Чтобы явно разрешить только определённые наборы инструментов, используйте переменные DBT_MCP_ENABLE_*. Если задана хотя бы одна такая переменная, активны только разрешённые наборы:

Имя	Значение по умолчанию	Описание
DBT_MCP_ENABLE_DBT_CLI	Не задано	Установите значение true, чтобы включить инструменты dbt CLI.
DBT_MCP_ENABLE_SEMANTIC_LAYER	Не задано	Установите значение true, чтобы включить инструменты Semantic Layer.
DBT_MCP_ENABLE_DISCOVERY	Не задано	Установите значение true, чтобы включить инструменты Discovery API.
DBT_MCP_ENABLE_ADMIN_API	Не задано	Установите значение true, чтобы включить инструменты Administrative API.
DBT_MCP_ENABLE_SQL	Не задано	Установите значение true, чтобы включить инструменты SQL.
DBT_MCP_ENABLE_DBT_CODEGEN	Не задано	Установите значение true, чтобы включить инструменты dbt codegen.
DBT_MCP_ENABLE_LSP	Не задано	Установите значение true, чтобы включить инструменты LSP/dbt v2.
DBT_MCP_ENABLE_TOOLS	Не задано	Список имён конкретных инструментов, которые нужно включить, разделённых запятыми.

Приоритет

Если задано несколько переменных, они обрабатываются в следующем порядке (начиная с наивысшего приоритета):

1. DBT_MCP_ENABLE_TOOLS (включение конкретных инструментов по имени)
2. DISABLE_TOOLS (отключение конкретных инструментов по имени)
3. Включение набора инструментов (DBT_MCP_ENABLE_*=true)
4. Отключение набора инструментов (DISABLE_*=true)
5. Поведение по умолчанию

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

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

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

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

Сообщить об ошибке в коде

Если используется файл .env: (укажите абсолютный путь, например к .env в корневом каталоге вашего проекта dbt)

uvx --env-file /absolute/path/to/your-dbt-project/.env dbt-mcp

Сообщить об ошибке в коде

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

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

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

• Claude
• Cursor
• VS Code

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

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

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

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

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

Симптомы: В вашем MCP-клиенте появляются сообщения об ошибках, такие как Could not connect to MCP server dbt-mcp, Error: spawn uvx ENOENT или spawn uvx ENOENT.

Причина: Ваш MCP-клиент (например, настольное приложение Claude) не может найти uvx в переменной PATH, поскольку запускается с ограниченным набором переменных окружения.

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

1. Найдите полный путь:

   • macOS/Linux: Выполните which uvx в терминале.
   • Windows: Выполните where uvx в командной строке или PowerShell.

2. Замените "command": "uvx" на вариант с полным путём:

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

Сообщить об ошибке в коде

Пример для macOS с Homebrew: "command": "/opt/homebrew/bin/uvx"

Для VS Code (mcp.json) применяется то же решение — замените uvx полным путём к нему в поле command.

Вход через OAuth не запускается

Симптомы: Окно браузера для входа через OAuth не открывается или процесс аутентификации зависает.

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

Решение:

1. Закройте клиент MCP (Claude Desktop, Cursor, VS Code и т. д.).
2. Удалите файлы конфигурации локально развернутого dbt MCP:
   • macOS/Linux: rm -f ~/.dbt/mcp.yml ~/.dbt/mcp.lock
   • Windows: Remove-Item -Force $env:USERPROFILE\.dbt\mcp.yml, $env:USERPROFILE\.dbt\mcp.lock
3. Перезапустите клиент и попробуйте подключиться снова.

Если эти действия не помогли устранить проблему, убедитесь, что для вашего аккаунта включены функции ИИ. Администратор аккаунта может включить их в разделе Account settings → Edit → включить переключатель Enable account access to dbt Wizard features. См. Включение dbt Wizard.

Все темы, связанные с устранением неполадок, см. в разделе Часто задаваемые вопросы о dbt MCP и устранение неполадок.

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

Создать GitHub Issue