# Интеграция Claude с dbt MCP Claude — это ИИ-ассистент от Anthropic с двумя основными интерфейсами: * [Claude Desktop](#claude-desktop): графический интерфейс с поддержкой MCP для доступа к файлам и выполнения команд, а также базовыми возможностями работы с кодом. * [Claude Code](#claude-code): инструмент для разработки в терминале или IDE. Оба интерфейса могут подключаться к одному из следующих серверов: * Локально развернутый сервер dbt MCP (работает на вашем компьютере, поддерживает команды CLI, например `dbt run`) * Удаленный сервер dbt MCP (HTTP, ориентирован на использование данных). Для OAuth локальная установка не требуется. Аутентификация на основе токена в Claude Desktop использует прокси `mcp-remote` и требует Node.js. ## Предварительные требования * Вы используете Claude для работы с ИИ или ИИ-агентами * Для OAuth (с локально развернутым или удаленным сервером) используйте свой [URL доступа со статическим поддоменом](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md). * OAuth для удаленного сервера MCP доступен для учетных записей Starter, Enterprise и Enterprise+. * После того как администратор настроит общие [учетные данные для аналитики](https://docs.getdbt.tech/docs/platform/wizard-read-only-users.md#set-up-analytics-credentials), пользователи с доступом только для чтения смогут использовать их вместо собственных учетных данных разработчика. Требуются статические поддомены Только учетные записи со статическими поддоменами (например, `abc123` в `abc123.us1.dbt.com`) могут использовать OAuth с MCP-серверами. Следуйте [этим инструкциям](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md), чтобы найти поддомен вашей учетной записи. Если у вашей учетной записи нет поддомена, обратитесь в службу поддержки за дополнительной информацией. ## Claude Desktop [Claude Desktop](https://claude.ai/download) считывает настройки серверов MCP из `claude_desktop_config.json`. Откройте этот файл через **Settings → Developer → Edit Config**. ### Настройка подключения к локально развернутому серверу dbt MCP Для быстрой первоначальной установки можно скачать готовый файл `.mcpb`; для более гибкой настройки отредактируйте JSON напрямую. подсказка Клонировать репозиторий dbt-mcp не нужно — для локального развертывания установите [uv](https://docs.astral.sh/uv/getting-started/installation/) и выполните `uvx dbt-mcp` (или воспользуйтесь конфигурациями, приведенными далее на этой странице). Клонируйте репозиторий только в том случае, если хотите [внести вклад в разработку dbt MCP](https://github.com/dbt-labs/dbt-mcp/issues). #### Быстрая установка с помощью файла .mcpb 1. Перейдите на страницу [последнего релиза dbt MCP](https://github.com/dbt-labs/dbt-mcp/releases/latest) и скачайте файл `dbt-mcp.mcpb`. 2. Дважды щелкните скачанный файл, чтобы открыть его в Claude Desktop. 3. Настройте **dbt platform Host**. Нужное значение можно найти в вашей учетной записи dbt platform: перейдите в **Account settings** и скопируйте **Access URL**. 4. Включите сервер в Claude Desktop. 5. Задайте Claude вопрос, связанный с данными, и посмотрите, как работает dbt MCP! #### Расширенная настройка Claude Desktop Используйте расширенную настройку, если хотите самостоятельно определить сервер dbt MCP в конфигурационном файле Claude — том же JSON-файле, в котором Claude хранит настройки всех серверов MCP в разделе `mcpServers`, с такими полями, как `command`, `args` и `env`. Базовый принцип описан в [примере установки MCP](https://modelcontextprotocol.io/quickstart/user#installing-the-filesystem-server). Чтобы открыть конфигурационный файл и добавить или заменить запись сервера dbt MCP: 1. В Claude перейдите в **Settings…** 2. В окне настроек выберите вкладку **Developer**. 3. Нажмите **Edit Config** и откройте файл в текстовом редакторе. 4. Добавьте конфигурацию сервера в раздел `mcpServers`. Выберите вариант, подходящий для вашего сценария использования:  Самостоятельно размещённый MCP с OAuth[Starter](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise +](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе") Конфигурация для пользователей, которым нужна удобная аутентификация OAuth в dbt platform. ### dbt platform only Этот вариант предназначен для пользователей, которым нужны только функции платформы dbt (Discovery API, Semantic Layer, управление заданиями) без самостоятельно размещаемых команд dbt platform CLI. Если вы используете только dbt platform, инструменты CLI автоматически отключаются. Значение поля `DBT_HOST` можно найти в информации о вашей учетной записи dbt platform в разделе **Access URLs**. ```json { "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**. ```json { "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.  Самостоятельно размещённый MCP (только CLI) Конфигурация для самостоятельного размещения для пользователей, которым нужно только выполнять команды dbt с dbt v1 или dbt v2 ```json { "mcpServers": { "dbt": { "command": "uvx", "args": ["dbt-mcp"], "env": { "DBT_PROJECT_DIR": "/path/to/your/dbt/project", "DBT_PATH": "/path/to/your/dbt/executable" } } } } ``` Как определить пути: * **DBT\_PROJECT\_DIR**: полный путь к папке, содержащей файл `dbt_project.yml` * **DBT\_PATH**: чтобы определить путь, выполните `which dbt` в терминале (macOS/Linux) или `where dbt` (Windows) в PowerShell  Самостоятельно размещённый MCP с .env Расширенная конфигурация для пользователей, которым нужны собственные [переменные окружения](https://docs.getdbt.tech/docs/dbt-ai/mcp-environment-variables.md). Поместите файл `.env` в *корневую папку проекта dbt* (ту же папку, где находится `dbt_project.yml`) и укажите абсолютный путь с помощью `--env-file`. Использование поля `env` (конфигурация в одном файле): Идентификаторы — это целые числа, а не URL-адреса `DBT_PROD_ENV_ID`, `DBT_DEV_ENV_ID` и `DBT_USER_ID` должны быть числовыми идентификаторами (например, `54321`), а не полными URL-адресами, скопированными из браузера. `DBT_HOST` принимает как `cloud.getdbt.com`, так и `https://cloud.getdbt.com`. Использование файла `.env` (укажите абсолютный путь к `.env` в корневой папке проекта dbt): ```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 (альтернативный вариант): ```json { "mcpServers": { "dbt": { "command": "uvx", "args": [ "--env-file", "/absolute/path/to/your-dbt-project/.env", "dbt-mcp" ] } } } ``` 5. Сохраните файл и перезапустите Claude Desktop. В правом нижнем углу поля ввода сообщения появится индикатор MCP-сервера. Дополнительные параметры конфигурации (переменные окружения, сервисные токены, настройки доступа к инструментам) описаны в разделе [Настройка самостоятельно размещённого MCP-сервера](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md). ### Подключение к удалённому MCP-серверу dbt Удалённый MCP-сервер dbt работает в dbt platform. Для OAuth Claude Desktop подключается по HTTP через пользовательский коннектор. Для аутентификации по токену используйте прокси `mcp-remote`, описанный на вкладке для токенов. Claude Desktop не принимает `"type": "http"` в `claude_desktop_config.json`. к сведению OAuth для удалённого MCP доступен в публичной бета-версии для учётных записей Starter, Enterprise и Enterprise+. Сначала получите свой MCP URL. Он понадобится для обоих способов аутентификации: Вы можете скопировать полный **MCP URL** в разделе **Account settings** → **Access URLs** → **MCP Endpoint URL** в dbt platform и вставить его непосредственно в свой ИИ-инструмент.  Составьте собственный MCP URL Рекомендуем использовать MCP URL из раздела **Account settings** → **Access URLs** → **MCP Endpoint URL** в dbt platform. Однако, если вы хотите составить собственный MCP URL, используйте свой **Access URL** из раздела **Account settings** в dbt platform. Удаленная конечная точка MCP — `https://YOUR_DBT_HOST_URL/api/ai/v1/mcp`. Замените `YOUR_DBT_HOST_URL` только именем хоста (без `https://`). Информацию о хостах по умолчанию, аккаунтах multi-cell и регионах см. в разделе [Доступ, регионы и IP-адреса](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md). Затем перейдите на вкладку, соответствующую вашему способу аутентификации: ### OAuth (remote) *OAuth для удалённого MCP доступен в публичной бета-версии для аккаунтов Starter, Enterprise и Enterprise+.* **Перед подключением** * Ваш MCP-клиент должен поддерживать OAuth для MCP-серверов, работающих по HTTP. Если такой поддержки нет, используйте [аутентификацию на основе токенов](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#token-based-authentication). * При первом подключении клиент открывает браузер для входа в систему. Затем dbt показывает экран согласия с запрашиваемыми областями доступа (конкретными разрешениями, которые клиенту будет позволено использовать) — описание каждой области доступа см. в разделе [Области доступа и согласие](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#scopes-and-consent). * Большинство современных MCP-клиентов регистрируются самостоятельно при первом подключении с помощью [динамической регистрации (RFC 7591)](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#dynamic-registration). Клиенты, которые её не поддерживают, администратор должен зарегистрировать в разделе **Account settings → Integrations → App integrations**. См. раздел [Ручная регистрация](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#manual-registration). Полное описание процесса, сеансов и ограничений см. в разделе [OAuth (удалённый MCP)](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#oauth-remote-mcp). Для использования OAuth добавьте dbt в качестве пользовательского коннектора в настройках Claude Desktop. Редактировать `claude_desktop_config.json` не требуется. Ниже описано, как подключить dbt в качестве пользовательского коннектора в Claude Desktop. Интерфейс зависит от инструмента, но порядок действий одинаков: добавьте пользовательский коннектор с вашим MCP URL, пройдите процедуру предоставления согласия OAuth, затем подключитесь. 1. В вашем ИИ-инструменте перейдите в настройки коннекторов и выберите добавление пользовательского коннектора (в Claude Desktop перейдите в **Chat → Customize → Connectors**, затем нажмите **Add custom connector**). 2. Введите имя (например, `dbt`) и вставьте MCP URL вашей dbt platform (например, `https://abc123.us1.dbt.com/api/ai/v1/mcp`), затем нажмите **Add**. [![Диалог добавления пользовательского коннектора с MCP URL dbt](/img/docs/dbt-cloud/oauth-add-custom-connector.png?v=2 "Диалог добавления пользовательского коннектора с MCP URL dbt")](#)Диалог добавления пользовательского коннектора с MCP URL dbt 3. Нажмите **Connect**. Инструмент перенаправит вас в dbt для прохождения процедуры предоставления согласия OAuth, где вы сможете разрешить или отклонить отдельные [области доступа](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#scopes-and-consent). [![Экран согласия OAuth с запрашиваемыми областями доступа и доступом к проектам](/img/docs/dbt-cloud/oauth-consent-screen.png?v=2 "Экран согласия OAuth с запрашиваемыми областями доступа и доступом к проектам")](#)Экран согласия OAuth с запрашиваемыми областями доступа и доступом к проектам 4. После вашего согласия коннектор будет добавлен в таблицу **Custom connectors** и будет отображаться как подключённый. [![Добавление пользовательского коннектора dbt в настройках коннекторов ИИ-инструмента](/img/docs/dbt-cloud/oauth-connectors-page.png?v=2 "Добавление пользовательского коннектора dbt в настройках коннекторов ИИ-инструмента")](#)Добавление пользовательского коннектора dbt в настройках коннекторов ИИ-инструмента 5. Готово 🎉! Задайте инструменту вопрос о данных, например *«Какова общая выручка за последние 30 дней?»*, чтобы проверить подключение. ### Token-based Используйте аутентификацию на основе токенов, если ваш клиент пока не поддерживает OAuth для HTTP-серверов MCP или если вам нужна общая конфигурация либо конфигурация для CI. `"type": "http"` недопустим в Claude Desktop Claude Desktop не поддерживает `"type": "http"` в `claude_desktop_config.json`. Если вставить этот блок (формат, который работает в `.mcp.json` в [Claude Code](#code-remote)), Claude Desktop пропустит сервер и покажет сообщение вроде «Не удалось загрузить некоторые серверы MCP». Вместо этого используйте конфигурацию прокси `mcp-remote` из шага 2. Для подключения к удалённому серверу MCP с аутентификацией на основе токенов в Claude Desktop требуется [Node.js](https://nodejs.org/), чтобы `npx` мог запускать `mcp-remote`. 1. В Claude Desktop перейдите в **Settings → Developer → Edit Config**, чтобы открыть `claude_desktop_config.json`. 2. Добавьте запись `dbt-remote` в `mcpServers`: ```json { "mcpServers": { "dbt-remote": { "command": "npx", "args": [ "mcp-remote", "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/", "--header", "Authorization: Token YOUR_DBT_ACCESS_TOKEN", "--header", "x-dbt-prod-environment-id: DBT_PROD_ENV_ID" ] } } } ``` Замените `YOUR_DBT_HOST_URL` именем вашего хоста (например, `abc123.us1.dbt.com`), а заполнители токена и идентификатора среды — своими значениями. Чтобы передать необязательные заголовки, такие как `x-dbt-user-id` или `x-dbt-dev-environment-id`, добавьте в массив `args` дополнительные пары `"--header"` и `"Header-Name: value"`. Для удалённого MCP с аутентификацией по токену задайте следующие заголовки в конфигурации MCP вашего клиента: * **`Authorization`** *(обязательный)* — `Token YOUR_DBT_ACCESS_TOKEN` или `Bearer YOUR_DBT_ACCESS_TOKEN`. Используйте [персональный токен доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md) или [сервисный токен](https://docs.getdbt.tech/docs/dbt-apis/service-tokens.md) с правами Developer для проекта, которому принадлежит среда, указанная в `x-dbt-prod-environment-id`. Назначьте сервисным токенам набор разрешений `Developer`. PAT наследуют разрешения своих создателей. Без прав Developer подключение завершается ошибкой `401`. * **`x-dbt-prod-environment-id`** *(обязательный)* — идентификатор вашей производственной среды dbt platform. Пошаговые инструкции см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md#dbt-prod-env-id). * **`x-dbt-dev-environment-id`** — обязателен для `execute_sql` и инструментов dbt v2. Пошаговые инструкции см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md#dbt-dev-env-id). * **`x-dbt-user-id`** — обязателен для `execute_sql`. Подробности см. в разделе [Где найти мой идентификатор пользователя?](https://docs.getdbt.tech/faqs/Accounts/find-user-id.md). Используйте числовые идентификаторы, а не полные URL-адреса В заголовках `x-dbt-prod-environment-id`, `x-dbt-dev-environment-id` и `x-dbt-user-id` ожидаются числовые идентификаторы (например, `54321`), а не полные URL-адреса, скопированные из браузера. URL-адрес хоста MCP должен содержать `https://` независимо от того, задаёте ли вы его в поле `url` или передаёте как аргумент `mcp-remote`. При аутентификации по токену для `execute_sql` требуется персональный токен доступа (PAT). Сервисные токены не подойдут. Чтобы выполнять SQL без создания PAT, используйте подключение через [OAuth (удалённый MCP)](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#oauth-remote-mcp). Полный список заголовков см. в разделе [Настройка удалённого MCP](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#token-based-authentication). Полный путь к `npx` Если Claude Desktop показывает `Server disconnected` или не может найти `npx`, задайте для `"command"` полный путь, полученный с помощью `which npx` (macOS или Linux) или `where npx` (Windows), например `"command": "/opt/homebrew/bin/npx"`. 3. Сохраните файл и перезапустите Claude Desktop. В разделе **Settings → Developer** убедитесь, что `dbt-remote` запущен. Задайте Claude вопрос о данных, чтобы убедиться, что сервер подключён. ## Claude Code [Claude Code](https://www.anthropic.com/claude-code) считывает конфигурацию MCP-серверов из `.mcp.json` в корне проекта (корне репозитория вашей рабочей области). Для самостоятельно размещённых серверов можно использовать ту же структуру `command` / `args` / `env`, что и в других клиентах. Для удалённой аутентификации на основе токенов Claude Code поддерживает `"type": "http"` в `.mcp.json`, в отличие от Claude Desktop. ### Настройка с самостоятельно размещённым сервером dbt MCP подсказка Клонировать репозиторий dbt-mcp не нужно — для самостоятельного размещения установите [uv](https://docs.astral.sh/uv/getting-started/installation/) и запустите `uvx dbt-mcp` (или используйте конфигурации ниже на этой странице). Клонируйте репозиторий, только если хотите [внести вклад в dbt MCP](https://github.com/dbt-labs/dbt-mcp/issues). 1. Следуйте инструкциям в разделе [Настройка самостоятельно размещённого MCP](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md), чтобы выбрать способ аутентификации: * OAuth с dbt platform * [Только CLI](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#cli-only) * [Переменные окружения](https://docs.getdbt.tech/docs/dbt-ai/setup-local-mcp.md#environment-variable-configuration) (включая файл `.env`, подключаемый через `--env-file`) 2. Создайте `.mcp.json` в корне проекта и добавьте запись `dbt` в ключ `mcpServers` верхнего уровня. Выберите вариант, подходящий для вашего сценария использования:  Самостоятельно размещённый MCP с OAuth[Starter](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе")[Enterprise +](https://www.getdbt.com/pricing "Подробнее о статусе или тарифе") Конфигурация для пользователей, которым нужна удобная аутентификация OAuth в dbt platform. ### dbt platform only Этот вариант предназначен для пользователей, которым нужны только функции платформы dbt (Discovery API, Semantic Layer, управление заданиями) без самостоятельно размещаемых команд dbt platform CLI. Если вы используете только dbt platform, инструменты CLI автоматически отключаются. Значение поля `DBT_HOST` можно найти в информации о вашей учетной записи dbt platform в разделе **Access URLs**. ```json { "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**. ```json { "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.  Самостоятельно размещённый MCP (только CLI) Конфигурация для самостоятельного размещения для пользователей, которым нужно только выполнять команды dbt с dbt v1 или dbt v2 ```json { "mcpServers": { "dbt": { "command": "uvx", "args": ["dbt-mcp"], "env": { "DBT_PROJECT_DIR": "/path/to/your/dbt/project", "DBT_PATH": "/path/to/your/dbt/executable" } } } } ``` Как определить пути: * **DBT\_PROJECT\_DIR**: полный путь к папке, содержащей файл `dbt_project.yml` * **DBT\_PATH**: чтобы определить путь, выполните `which dbt` в терминале (macOS/Linux) или `where dbt` (Windows) в PowerShell  Самостоятельно размещённый MCP с .env Расширенная конфигурация для пользователей, которым нужны собственные [переменные окружения](https://docs.getdbt.tech/docs/dbt-ai/mcp-environment-variables.md). Поместите файл `.env` в *корневую папку проекта dbt* (ту же папку, где находится `dbt_project.yml`) и укажите абсолютный путь с помощью `--env-file`. Использование поля `env` (конфигурация в одном файле): Идентификаторы — это целые числа, а не URL-адреса `DBT_PROD_ENV_ID`, `DBT_DEV_ENV_ID` и `DBT_USER_ID` должны быть числовыми идентификаторами (например, `54321`), а не полными URL-адресами, скопированными из браузера. `DBT_HOST` принимает как `cloud.getdbt.com`, так и `https://cloud.getdbt.com`. Использование файла `.env` (укажите абсолютный путь к `.env` в корневой папке проекта dbt): ```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 (альтернативный вариант): ```json { "mcpServers": { "dbt": { "command": "uvx", "args": [ "--env-file", "/absolute/path/to/your-dbt-project/.env", "dbt-mcp" ] } } } ``` О команде `claude mcp add` CLI Claude Code позволяет регистрировать MCP-серверы с помощью `claude mcp add`, но обычно записывает их в конфигурацию уровня пользователя (`~/.claude.json`), а не в `.mcp.json` проекта. Для dbt MCP мы рекомендуем сохранять `.mcp.json` в вашем репозитории, чтобы конфигурация действовала на уровне проекта и ею было проще делиться. ### Настройка с удалённым сервером dbt MCP Claude Code может подключаться к удалённому серверу dbt MCP по HTTP с помощью `"type": "http"` в `.mcp.json`. Эта структура конфигурации HTTP предназначена для Claude Code (и аналогичных клиентов), а не для `claude_desktop_config.json` в Claude Desktop. к сведению OAuth для удалённого MCP доступен в публичной бета-версии для учётных записей Starter, Enterprise и Enterprise+. 1. Откройте `.mcp.json` в корне проекта (создайте его, если он ещё не существует). 2. Получите URL вашего MCP-сервера: Вы можете скопировать полный **MCP URL** в разделе **Account settings** → **Access URLs** → **MCP Endpoint URL** в dbt platform и вставить его непосредственно в свой ИИ-инструмент.  Составьте собственный MCP URL Рекомендуем использовать MCP URL из раздела **Account settings** → **Access URLs** → **MCP Endpoint URL** в dbt platform. Однако, если вы хотите составить собственный MCP URL, используйте свой **Access URL** из раздела **Account settings** в dbt platform. Удаленная конечная точка MCP — `https://YOUR_DBT_HOST_URL/api/ai/v1/mcp`. Замените `YOUR_DBT_HOST_URL` только именем хоста (без `https://`). Информацию о хостах по умолчанию, аккаунтах multi-cell и регионах см. в разделе [Доступ, регионы и IP-адреса](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md). 3. Добавьте запись `dbt` в `.mcp.json`, используя вкладку, соответствующую вашему способу аутентификации: ### OAuth (удалённый сервер) *OAuth для удалённого MCP доступен в публичной бета-версии для учётных записей Starter, Enterprise и Enterprise+.* **Перед подключением** * Ваш MCP-клиент должен поддерживать OAuth для MCP-серверов, работающих по HTTP. Если такой поддержки нет, используйте [аутентификацию на основе токенов](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#token-based-authentication). * При первом подключении клиент открывает браузер для входа в систему. Затем dbt показывает экран согласия с запрашиваемыми областями доступа (конкретными разрешениями, которые клиенту будет позволено использовать) — описание каждой области доступа см. в разделе [Области доступа и согласие](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#scopes-and-consent). * Большинство современных MCP-клиентов регистрируются самостоятельно при первом подключении с помощью [динамической регистрации (RFC 7591)](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#dynamic-registration). Клиенты, которые её не поддерживают, администратор должен зарегистрировать в разделе **Account settings → Integrations → App integrations**. См. раздел [Ручная регистрация](https://docs.getdbt.tech/docs/platform/manage-access/connect-apps-oauth.md#manual-registration). Полное описание процесса, сеансов и ограничений см. в разделе [OAuth (удалённый MCP)](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#oauth-remote-mcp). Добавьте следующую конфигурацию в `.mcp.json` в корне проекта. При первом подключении Claude Code откроет браузер для входа и предоставления разрешений. ```json { "mcpServers": { "dbt": { "type": "http", "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/" } } } ``` Замените `YOUR_DBT_HOST_URL` на имя вашего хоста (например, `abc123.us1.dbt.com`). URL можно найти в dbt platform в разделе **Account settings** → **Access URLs** → **MCP Endpoint URL**. Вы также можете зарегистрировать этот же сервер через CLI: ```bash claude mcp add --transport http dbt https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/ ``` ### На основе токена ```json { "mcpServers": { "dbt": { "type": "http", "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/", "headers": { "Authorization": "Token YOUR_DBT_ACCESS_TOKEN", "x-dbt-prod-environment-id": "DBT_PROD_ENV_ID", "x-dbt-user-id": "DBT_USER_ID", "x-dbt-dev-environment-id": "DBT_DEV_ENV_ID" } } } } ``` Для удалённого MCP с аутентификацией по токену задайте следующие заголовки в конфигурации MCP вашего клиента: * **`Authorization`** *(обязательный)* — `Token YOUR_DBT_ACCESS_TOKEN` или `Bearer YOUR_DBT_ACCESS_TOKEN`. Используйте [персональный токен доступа (PAT)](https://docs.getdbt.tech/docs/dbt-apis/user-tokens.md) или [сервисный токен](https://docs.getdbt.tech/docs/dbt-apis/service-tokens.md) с правами Developer для проекта, которому принадлежит среда, указанная в `x-dbt-prod-environment-id`. Назначьте сервисным токенам набор разрешений `Developer`. PAT наследуют разрешения своих создателей. Без прав Developer подключение завершается ошибкой `401`. * **`x-dbt-prod-environment-id`** *(обязательный)* — идентификатор вашей производственной среды dbt platform. Пошаговые инструкции см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md#dbt-prod-env-id). * **`x-dbt-dev-environment-id`** — обязателен для `execute_sql` и инструментов dbt v2. Пошаговые инструкции см. в разделе [Как найти идентификаторы dbt MCP](https://docs.getdbt.tech/docs/dbt-ai/mcp-find-ids.md#dbt-dev-env-id). * **`x-dbt-user-id`** — обязателен для `execute_sql`. Подробности см. в разделе [Где найти мой идентификатор пользователя?](https://docs.getdbt.tech/faqs/Accounts/find-user-id.md). Используйте числовые идентификаторы, а не полные URL-адреса В заголовках `x-dbt-prod-environment-id`, `x-dbt-dev-environment-id` и `x-dbt-user-id` ожидаются числовые идентификаторы (например, `54321`), а не полные URL-адреса, скопированные из браузера. URL-адрес хоста MCP должен содержать `https://` независимо от того, задаёте ли вы его в поле `url` или передаёте как аргумент `mcp-remote`. При аутентификации по токену для `execute_sql` требуется персональный токен доступа (PAT). Сервисные токены не подойдут. Чтобы выполнять SQL без создания PAT, используйте подключение через [OAuth (удалённый MCP)](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#oauth-remote-mcp). Полный список заголовков см. в разделе [Настройка удалённого MCP](https://docs.getdbt.tech/docs/dbt-ai/setup-remote-mcp.md#token-based-authentication). 4. Сохраните файл. Claude Code считывает `.mcp.json` при запуске — задайте ему вопрос о данных, чтобы проверить подключение. ## Устранение неполадок Ошибки Claude Desktop Claude Desktop может возвращать такие ошибки, как `Error: spawn uvx ENOENT`, `Error: spawn npx ENOENT`, `Could not connect to MCP server dbt-mcp` или `Server disconnected`. Для установок на собственной инфраструктуре замените значение `command` полным путём к `uvx`: выполните `which uvx` в Unix-системах или `where uvx` в Windows и вставьте полный путь в JSON (например, `"command": "/the/full/path/to/uvx"`). Для удалённых подключений через `mcp-remote` с аутентификацией по токену аналогичным образом укажите полный путь к `npx`. Если Claude сообщает, что записи в `claude_desktop_config.json` недопустимы и были пропущены, убедитесь, что в этом файле не используется `"type": "http"`. Вместо этого используйте [конфигурацию `mcp-remote` с аутентификацией по токену](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-claude.md#desktop-remote). Для удалённых подключений ещё раз проверьте, что URL-адрес MCP заканчивается на `/api/ai/v1/mcp/` (включая завершающий слеш), а значение заголовка `Authorization` — `Token YOUR_DBT_ACCESS_TOKEN` или `Bearer YOUR_DBT_ACCESS_TOKEN`. Логи находятся в `~/Library/Logs/Claude` (macOS) или `%APPDATA%\Claude\logs` (Windows). Claude Code не может подключиться к серверу dbt MCP Если подключение к серверу dbt MCP не устанавливается, убедитесь, что файл `.mcp.json` находится в *корне проекта*, а блок `dbt` соответствует одному из примеров на [странице настройки Claude](https://docs.getdbt.tech/docs/dbt-ai/integrate-mcp-claude.md#claude-code). Для самостоятельно размещённых установок аналогичным образом укажите полный путь к `uvx` (а также полные пути в `--env-file`). При удалённом подключении проверьте URL и заголовки, а затем для сравнения попробуйте эквивалентную команду `claude mcp add --transport http`.