# Подключение dbt MCP к платформе dbt [Назад к гайдам](https://docs.getdbt.tech/guides.md) [Menu ]() В этом кратком руководстве используется локальный сервер MCP: он запускается на вашем компьютере с помощью `uvx dbt-mcp`, подключается к dbt platform для работы с Semantic Layer, Discovery и SQL, а также при необходимости запускает dbt локально. Если вам нужен только самостоятельно развернутый CLI (с аккаунтом dbt platform или без него), см. [Запуск самостоятельно развернутого dbt](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-cli.md) или [Запуск самостоятельно развернутого dbt Wizard](https://docs.getdbt.tech/docs/platform/wizard-overview.md#get-started). Чтобы настроить или отключить отдельные инструменты, см. [Справочник переменных окружения](https://docs.getdbt.tech/docs/dbt-ai/mcp-environment-variables.md). ## Предварительные требования * [Установите uv](https://docs.astral.sh/uv/getting-started/installation/) * [Аккаунт dbt platform](https://www.getdbt.com/signup) * Для подключений через OAuth: * MCP OAuth доступен на тарифах Starter, Enterprise и Enterprise+. ## Шаг 1. Выберите способ аутентификации и выполните настройку ### OAuth *MCP OAuth доступен в публичной бета-версии для аккаунтов на тарифах Starter, Enterprise и Enterprise+.* OAuth — самый быстрый способ настройки для аккаунтов dbt platform: вам не нужно копировать токены или управлять ими. При первом подключении открывается окно браузера для аутентификации. Для использования OAuth *без* самостоятельно развернутой установки используйте [удаленный сервер MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-remote.md). OAuth для удаленного MCP доступен в публичной бета-версии для аккаунтов на тарифах Starter, Enterprise и Enterprise+. Если ваш клиент не поддерживает OAuth или вам нужен доступ по токену, используйте [аутентификацию по токену](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#token-based-authentication). Требуются статические поддомены Только учетные записи со статическими поддоменами (например, `abc123` в `abc123.us1.dbt.com`) могут использовать OAuth с MCP-серверами. Следуйте [этим инструкциям](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md), чтобы найти поддомен вашей учетной записи. Если у вашей учетной записи нет поддомена, обратитесь в службу поддержки за дополнительной информацией. #### Найдите свой Access URL 1. Войдите в свой аккаунт dbt platform. 2. Перейдите в **Account settings** и скопируйте **Access URL** (например, `abc123.us1.dbt.com`). Multi-cell и формат DBT\_HOST * Поле `DBT_HOST` принимает как `abc123.us1.dbt.com`, так и `https://abc123.us1.dbt.com`. * Если ваш Access URL — `abc123.us1.dbt.com`, разделите его на две переменные: * `DBT_HOST=us1.dbt.com` * `MULTICELL_ACCOUNT_PREFIX=abc123` Не включайте префикс аккаунта в `DBT_HOST`. Подробнее см. в [примерах настройки multi-cell](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#api-and-sql-tool-settings). #### Добавьте конфигурацию в свой клиент MCP ### Claude Desktop **Вариант A: быстрая установка (рекомендуется)** 1. Перейдите к [последнему релизу dbt MCP](https://github.com/dbt-labs/dbt-mcp/releases/latest) и скачайте `dbt-mcp.mcpb`. 2. Дважды щелкните файл, чтобы открыть его в Claude Desktop. 3. Введите свой **Access URL** в качестве хоста dbt platform. 4. Включите сервер. **Вариант B: ручная настройка** 1. В Claude Desktop перейдите в **Settings** → вкладка **Developer** → **Edit Config**. 2. Вставьте следующую конфигурацию, заменив `YOUR-ACCESS-URL` своим Access URL: ```json { "mcpServers": { "dbt": { "command": "uvx", "args": ["dbt-mcp"], "env": { "DBT_HOST": "YOUR-ACCESS-URL" } } } } ``` 3. Сохраните изменения и перезапустите Claude Desktop. Расположение файла конфигурации: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` ### Claude Code Выполните эту команду, заменив `YOUR-ACCESS-URL` своим Access URL: ```shell claude mcp add dbt \ -e DBT_HOST=YOUR-ACCESS-URL \ -- uvx dbt-mcp ``` Например, если ваш Access URL — `abc123.us1.dbt.com`: ```shell claude mcp add dbt \ -e DBT_HOST=abc123.us1.dbt.com \ -- uvx dbt-mcp ``` ### Cursor При открытом Cursor нажмите одну из ссылок ниже для автоматической настройки, затем замените значение-заполнитель своим Access URL: * [Только dbt platform (OAuth)](cursor://anysphere.cursor-deeplink/mcp/install?name=dbt\&config=eyJlbnYiOnsiREJUX0hPU1QiOiJZT1VSLUFDQ0VTUy1VUkwiLCJESVNBQkxFX0RCVF9DTEkiOiJ0cnVlIn0sImNvbW1hbmQiOiJ1dngiLCJhcmdzIjpbImRidC1tY3AiXX0%3D) — только возможности платформы, без CLI * [dbt platform + CLI (OAuth)](cursor://anysphere.cursor-deeplink/mcp/install?name=dbt\&config=eyJlbnYiOnsiREJUX0hPU1QiOiJZT1VSLUFDQ0VTUy1VUkwiLCJEQlRfUFJPSkVDVF9ESVIiOiIvcGF0aC90by9wcm9qZWN0IiwiREJUX1BBVEgiOiJwYXRoL3RvL2RidC9leGVjdXRhYmxlIn0sImNvbW1hbmQiOiJ1dngiLCJhcmdzIjpbImRidC1tY3AiXX0%3D) — возможности платформы + команды самостоятельно развернутого dbt CLI После перехода по ссылке замените `YOUR-ACCESS-URL` своим фактическим Access URL (например, `abc123.us1.dbt.com`) и сохраните изменения. ### VS Code 1. Откройте **Settings** → **Features** → **Chat** и убедитесь, что **MCP** включен. 2. Откройте палитру команд (`Ctrl/Cmd + Shift + P`) и выберите **MCP: Open User Configuration**. 3. Добавьте следующую конфигурацию в `mcp.json`: VS Code использует `"servers"`, а не `"mcpServers"` ```json { "servers": { "dbt": { "command": "uvx", "args": ["dbt-mcp"], "env": { "DBT_HOST": "YOUR-ACCESS-URL" } } } } ``` Замените `YOUR-ACCESS-URL` своим Access URL (например, `abc123.us1.dbt.com`) и сохраните изменения. #### Необязательно: добавьте команды самостоятельно развернутого dbt CLI Чтобы также выполнять команды dbt platform CLI (`dbt run`, `dbt build`, `dbt test` и другие), добавьте эти две переменные в блок `env`: ```json "DBT_PROJECT_DIR": "/path/to/your/dbt/project", "DBT_PATH": "/path/to/your/dbt/executable" ``` Найдите `DBT_PATH`, выполнив `which dbt` (macOS/Linux) или `where dbt` (Windows). `DBT_PROJECT_DIR` — это папка, содержащая ваш `dbt_project.yml`. ### Токены Аутентификация по токену дает больше контроля и лучше подходит для общих или командных конфигураций. Вам понадобится сервисный токен или персональный токен доступа (PAT). Какой токен использовать? * **PAT (Personal Access Token):** необходим для использования `execute_sql`. Привязан к вашей учетной записи пользователя. * **Сервисный токен:** подходит для всех остальных наборов инструментов платформы. Лучше подходит для общих или командных конфигураций. Подробные рекомендации см. в разделе [Выбор способа аутентификации](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#choose-your-auth-method). ### Найдите свои пути и идентификаторы Вам понадобятся следующие значения. Пошаговые инструкции см. в разделе [Поиск идентификаторов](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md). | Переменная | Где найти | | ----------------- | --------------------------------------------------------------------- | | `DBT_HOST` | Имя хоста dbt platform в **Account settings** → **Access URL** | | `DBT_TOKEN` | Сервисный токен или PAT в **Account settings** → **API tokens** | | `DBT_PROD_ENV_ID` | Идентификатор производственной среды в **Deploy** → **Environments** | | `DBT_DEV_ENV_ID` | Идентификатор среды разработки (необходим для `execute_sql`) | | `DBT_USER_ID` | Ваш числовой идентификатор пользователя (необходим для `execute_sql`) | | `DBT_ACCOUNT_ID` | Идентификатор аккаунта (необходим для инструментов Admin API) | Используйте только значения, а не полные URL Эти переменные принимают имена хостов или числовые идентификаторы, а не полные URL: ```bash # ✅ Правильно 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 ``` Аккаунты multi-cell Если ваш Access URL — `abc123.us1.dbt.com`, разделите его на две переменные: * `DBT_HOST=us1.dbt.com` * `MULTICELL_ACCOUNT_PREFIX=abc123` Не включайте префикс аккаунта в `DBT_HOST`. Подробнее см. в [примерах настройки multi-cell](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#api-and-sql-tool-settings). ### Добавьте конфигурацию в свой клиент MCP Используйте приведенную ниже конфигурацию, заменив значения-заполнители найденными выше идентификаторами. Включайте только нужные вам переменные: ### Claude Desktop 1. В Claude Desktop перейдите в **Settings** → вкладка **Developer** → **Edit Config**. 2. Вставьте следующую конфигурацию, заменив значения-заполнители: ```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_DEV_ENV_ID": "67890", "DBT_USER_ID": "123", "DBT_ACCOUNT_ID": "99999" } } } } ``` 3. Сохраните изменения и перезапустите Claude Desktop. Расположение файла конфигурации: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` ### Claude Code Выполните эту команду, заменив значения-заполнители своими фактическими значениями: ```bash claude mcp add dbt \ -e DBT_HOST=cloud.getdbt.com \ -e DBT_TOKEN=your-token-here \ -e DBT_PROD_ENV_ID=12345 \ -- uvx dbt-mcp ``` Добавьте `-e DBT_DEV_ENV_ID=...` и `-e DBT_USER_ID=...`, если используете `execute_sql`; добавьте `-e DBT_ACCOUNT_ID=...` для Admin API. ### Cursor 1. В Cursor откройте **Settings** → **MCP** → **Edit config** (или свой файл конфигурации). 2. Вставьте следующую конфигурацию, заменив значения-заполнители: ```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_DEV_ENV_ID": "67890", "DBT_USER_ID": "123", "DBT_ACCOUNT_ID": "99999" } } } } ``` 3. Сохраните конфигурацию. ### VS Code 1. Откройте **Settings** → **Features** → **Chat** и убедитесь, что **MCP** включен. 2. Откройте палитру команд (`Ctrl/Cmd + Shift + P`) и выберите **MCP: Open User Configuration**. 3. Добавьте следующую конфигурацию в `mcp.json`: VS Code использует `"servers"`, а не `"mcpServers"` ```json { "servers": { "dbt": { "command": "uvx", "args": ["dbt-mcp"], "env": { "DBT_HOST": "cloud.getdbt.com", "DBT_TOKEN": "your-token-here", "DBT_PROD_ENV_ID": "12345", "DBT_DEV_ENV_ID": "67890", "DBT_USER_ID": "123", "DBT_ACCOUNT_ID": "99999" } } } } ``` 4. Сохраните `mcp.json` и перезапустите VS Code.  Необязательно: добавьте команды самостоятельно развернутого dbt CLI Чтобы также выполнять команды dbt (`dbt run`, `dbt build`, `dbt test` и другие), добавьте эти две переменные в блок `env`: ```json "DBT_PROJECT_DIR": "/path/to/your/dbt/project", "DBT_PATH": "/path/to/your/dbt/executable" ``` Найдите `DBT_PATH`, выполнив `which dbt` (macOS/Linux) или `where dbt` (Windows). `DBT_PROJECT_DIR` — это папка, содержащая ваш `dbt_project.yml`. ## Шаг 2. Пройдите аутентификацию ### OAuth При первом подключении dbt MCP открывает окно браузера для завершения аутентификации OAuth. После входа ваш сеанс сохраняется, и последующие подключения выполняются автоматически. Если аутентификация не начинается, закройте клиент и выполните: * macOS/Linux: `rm -f ~/.dbt/mcp.yml ~/.dbt/mcp.lock` * Windows: `Remove-Item -Force $env:USERPROFILE\.dbt\mcp.yml, $env:USERPROFILE\.dbt\mcp.lock` Затем перезапустите клиент. ### Токены Дополнительный шаг аутентификации не требуется — ваш токен уже указан в конфигурации. Сервер подключается автоматически при запуске клиента MCP. ## Шаг 3. Проверьте настройку Задайте своему ИИ-ассистенту вопрос о данных (например, *«Какие модели есть в моем проекте dbt?»* или *«Какие метрики определены в моем Semantic Layer?»*). Если dbt MCP работает, в ответе будут использованы ваши метаданные dbt. ## Доступные возможности При подключении к платформе ваш ИИ-ассистент может использовать: * Запросы к Semantic Layer * Discovery для метаданных (происхождение моделей, результаты тестов, свежесть источников) * Admin API (запуск заданий, получение списка запусков и артефактов) * Выполнение SQL и преобразование текста в SQL (требуется [PAT](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md)) * Все команды dbt, если вы добавили `DBT_PROJECT_DIR` и `DBT_PATH` Полный список инструментов см. в разделе [Доступные инструменты](https://docs.getdbt.tech/docs/dbt-ai/mcp-available-tools.md). Нужен только самостоятельно развернутый dbt CLI? Если вам нужно только выполнять команды dbt локально (с аккаунтом dbt platform или без него), см. [Запуск самостоятельно развернутого dbt](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-cli.md). ## Устранение неполадок Не удаётся найти исполняемый файл 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"` на вариант с полным путём: ```json { "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](https://docs.getdbt.tech/docs/platform/manage-dbt-ai.md). Сервер не запускается **Симптомы:** MCP-сервер отображается в вашем клиенте как отключённый или недоступный. **Диагностика:** Проверьте журналы сервера: * **VS Code:** Откройте палитру команд (`Ctrl/Cmd + Shift + P`) → `MCP: List Servers` → нажмите на сервер dbt, чтобы просмотреть подробные журналы. * **Claude Desktop:** Проверьте `~/Library/Logs/Claude` (macOS) или `%APPDATA%\Claude\logs` (Windows). * **Все клиенты:** Задайте `DBT_MCP_LOG_LEVEL=DEBUG` в переменных окружения, чтобы получать более подробный вывод. **Распространённые причины:** * Отсутствующее или некорректное значение (Версии dbt: v1.11 и новее) `DBT_ENGINE_PROJECT_DIR` или `DBT_PATH` — убедитесь, что указанные пути существуют и являются абсолютными. * Недействительные токены аутентификации или токены с истёкшим сроком действия — создайте новый токен и обновите конфигурацию. * Отсутствие обязательных переменных окружения для набора инструментов, который вы пытаетесь использовать — см. [Требования инструментов](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#tool-requirements-at-a-glance). Инструмент execute\_sql не работает **Симптомы:** Инструмент `execute_sql` возвращает ошибку аутентификации или недоступен. **Причина:** Способ устранения проблемы зависит от того, как вы подключились: * **Удалённый MCP с OAuth:** Войдите в систему через свой MCP-клиент, когда появится соответствующий запрос. Персональный токен доступа не требуется. * **Удалённый MCP с аутентификацией по токену:** Вам нужен [персональный токен доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md). Сервисные токены не подойдут. Также необходимы заголовки `x-dbt-dev-environment-id` и `x-dbt-user-id`. Идентификатор пользователя должен соответствовать пользователю, создавшему PAT. * **Локальный MCP:** Задайте для `DBT_TOKEN` значение персонального токена доступа (PAT). Сервисные токены не подойдут. **Решение:** 1. Если вы используете OAuth для удалённого MCP, убедитесь, что вы выполнили вход и предоставили согласие в своём MCP-клиенте. 2. Если вы используете аутентификацию по токену или локальный MCP, создайте [персональный токен доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md) в разделе **Account settings** → **API tokens** → **Personal tokens**. 3. Для удалённого MCP с аутентификацией по токену добавьте PAT в заголовок `Authorization` в виде `Token YOUR_PAT`. Для локального MCP задайте PAT в качестве значения `DBT_TOKEN`. 4. Также убедитесь, что заданы `DBT_DEV_ENV_ID` и `DBT_USER_ID` (для локального MCP) или заголовки `x-dbt-dev-environment-id` и `x-dbt-user-id` (для удалённого MCP). Подробности см. в разделе [Поиск идентификаторов](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md). Набор инструментов недоступен или отображается как отключённый **Симптомы:** Набор инструментов (Semantic Layer, Discovery, Admin API) недоступен в вашем ИИ-клиенте, хотя учётные данные настроены. **Причина:** Отсутствуют обязательные переменные либо набор инструментов явно отключён. **Решение:** 1. Проверьте, что все обязательные переменные для набора инструментов заданы — см. [Требования к инструментам](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#tool-requirements-at-a-glance). 2. Проверьте, нет ли у вас переменных `DISABLE_*` со значением `true`, которые могут отключать набор инструментов. 3. Если вы используете режим явного включения (`DBT_MCP_ENABLE_*`), убедитесь, что нужный набор инструментов указан среди включённых. 4. Задайте `DBT_MCP_LOG_LEVEL=DEBUG`, чтобы увидеть, какие наборы инструментов активны при запуске. Вставка полных URL вместо идентификаторов **Симптомы:** Ошибки аутентификации, непредвиденное поведение или невозможность подключения сервера к нужной среде. **Причина:** Переменные среды, такие как `DBT_PROD_ENV_ID`, `DBT_USER_ID` и `DBT_ACCOUNT_ID`, принимают целые числа, а не полные URL из браузера. **Решение:** ```bash # ✅ Правильно 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 ``` Пошаговые инструкции приведены в разделе [Как найти свои идентификаторы](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md). Проблемы с подключением к аккаунту в multi-cell или со статическим поддоменом **Симптомы:** Ошибки подключения, когда URL вашего аккаунта содержит префикс (например, `abc123.us1.dbt.com`). **Решение (начиная с v1.14.0):** Задайте для `DBT_HOST` полное имя хоста, включая префикс. Если вы используете аутентификацию на основе PAT, также задайте `DBT_ACCOUNT_ID`. ```bash # ✅ Правильно DBT_HOST=abc123.us1.dbt.com DBT_ACCOUNT_ID=12345 # требуется для аутентификации на основе PAT ``` Больше не нужно задавать `MULTICELL_ACCOUNT_PREFIX` или `DBT_HOST_PREFIX`. Если эти переменные заданы в вашей старой конфигурации, удалите их. Все темы по устранению неполадок см. в разделе [Часто задаваемые вопросы о dbt MCP и устранение неполадок](https://docs.getdbt.tech/docs/dbt-ai/mcp-troubleshooting.md). ## Следующие шаги * Выполняйте команды dbt локально: см. [Запуск самостоятельно развернутого dbt](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-cli.md) * Настройте отдельные наборы инструментов: см. [Справочник переменных окружения](https://docs.getdbt.tech/docs/dbt-ai/mcp-environment-variables.md) * Изучите требования наборов инструментов: см. [Настройка самостоятельно развернутого MCP](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#tool-requirements-at-a-glance)