Интеграция Claude с dbt MCP

Claude — это ИИ-ассистент от Anthropic с двумя основными интерфейсами:

• Claude Desktop: графический интерфейс с поддержкой MCP для доступа к файлам и выполнения команд, а также базовыми возможностями работы с кодом.
• Claude Code: инструмент для разработки в терминале или IDE.

Оба интерфейса могут подключаться к одному из следующих серверов:

• Локально развернутый сервер dbt MCP (работает на вашем компьютере, поддерживает команды CLI, например dbt run)
• Удаленный сервер dbt MCP (HTTP, ориентирован на использование данных). Для OAuth локальная установка не требуется. Аутентификация на основе токена в Claude Desktop использует прокси mcp-remote и требует Node.js.

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

• Вы используете Claude для работы с ИИ или ИИ-агентами
• Для OAuth (с локально развернутым или удаленным сервером) используйте свой URL доступа со статическим поддоменом.
  • OAuth для удаленного сервера MCP доступен для учетных записей Starter, Enterprise и Enterprise+.

• После того как администратор настроит общие учетные данные для аналитики, пользователи с доступом только для чтения смогут использовать их вместо собственных учетных данных разработчика.

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

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

Claude Desktop

Claude Desktop считывает настройки серверов MCP из claude_desktop_config.json. Откройте этот файл через Settings → Developer → Edit Config.

Настройка подключения к локально развернутому серверу dbt MCP

Для быстрой первоначальной установки можно скачать готовый файл .mcpb; для более гибкой настройки отредактируйте JSON напрямую.

подсказка

Клонировать репозиторий dbt-mcp не нужно — для локального развертывания установите uv и выполните uvx dbt-mcp (или воспользуйтесь конфигурациями, приведенными далее на этой странице). Клонируйте репозиторий только в том случае, если хотите внести вклад в разработку dbt MCP.

Быстрая установка с помощью файла .mcpb

1. Перейдите на страницу последнего релиза dbt MCP и скачайте файл 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.

Чтобы открыть конфигурационный файл и добавить или заменить запись сервера dbt MCP:

1. В Claude перейдите в Settings…

2. В окне настроек выберите вкладку Developer.

3. Нажмите Edit Config и откройте файл в текстовом редакторе.

4. Добавьте конфигурацию сервера в раздел mcpServers. Выберите вариант, подходящий для вашего сценария использования:

    Самостоятельно размещённый MCP с OAuthStarterEnterpriseEnterprise +

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

   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.

    Самостоятельно размещённый MCP (только CLI)

   Конфигурация для самостоятельного размещения для пользователей, которым нужно только выполнять команды dbt с dbt v1 или dbt v2

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

   Расширенная конфигурация для пользователей, которым нужны собственные переменные окружения. Поместите файл .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):

   {
     "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 (альтернативный вариант):

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

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

5. Сохраните файл и перезапустите Claude Desktop. В правом нижнем углу поля ввода сообщения появится индикатор MCP-сервера.

Дополнительные параметры конфигурации (переменные окружения, сервисные токены, настройки доступа к инструментам) описаны в разделе Настройка самостоятельно размещённого MCP-сервера.

Подключение к удалённому 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-адреса.

Затем перейдите на вкладку, соответствующую вашему способу аутентификации:

OAuth (remote)

OAuth для удалённого MCP доступен в публичной бета-версии для аккаунтов Starter, Enterprise и Enterprise+.

Перед подключением

• Ваш MCP-клиент должен поддерживать OAuth для MCP-серверов, работающих по HTTP. Если такой поддержки нет, используйте аутентификацию на основе токенов.
• При первом подключении клиент открывает браузер для входа в систему. Затем dbt показывает экран согласия с запрашиваемыми областями доступа (конкретными разрешениями, которые клиенту будет позволено использовать) — описание каждой области доступа см. в разделе Области доступа и согласие.
• Большинство современных MCP-клиентов регистрируются самостоятельно при первом подключении с помощью динамической регистрации (RFC 7591). Клиенты, которые её не поддерживают, администратор должен зарегистрировать в разделе Account settings → Integrations → App integrations. См. раздел Ручная регистрация.

Полное описание процесса, сеансов и ограничений см. в разделе OAuth (удалённый 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
3. Нажмите Connect. Инструмент перенаправит вас в dbt для прохождения процедуры предоставления согласия OAuth, где вы сможете разрешить или отклонить отдельные области доступа.
   Экран согласия OAuth с запрашиваемыми областями доступа и доступом к проектам
4. После вашего согласия коннектор будет добавлен в таблицу Custom connectors и будет отображаться как подключённый.
   Добавление пользовательского коннектора 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), Claude Desktop пропустит сервер и покажет сообщение вроде «Не удалось загрузить некоторые серверы MCP».

Вместо этого используйте конфигурацию прокси mcp-remote из шага 2.

Для подключения к удалённому серверу MCP с аутентификацией на основе токенов в Claude Desktop требуется Node.js, чтобы npx мог запускать mcp-remote.

1. В Claude Desktop перейдите в Settings → Developer → Edit Config, чтобы открыть claude_desktop_config.json.

2. Добавьте запись dbt-remote в mcpServers:

   {
     "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) или сервисный токен с правами Developer для проекта, которому принадлежит среда, указанная в x-dbt-prod-environment-id. Назначьте сервисным токенам набор разрешений Developer. PAT наследуют разрешения своих создателей. Без прав Developer подключение завершается ошибкой 401.
   • x-dbt-prod-environment-id (обязательный) — идентификатор вашей производственной среды dbt platform. Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.
   • x-dbt-dev-environment-id — обязателен для execute_sql и инструментов dbt v2. Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.
   • x-dbt-user-id — обязателен для execute_sql. Подробности см. в разделе Где найти мой идентификатор пользователя?.
   Используйте числовые идентификаторы, а не полные 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). Полный список заголовков см. в разделе Настройка удалённого MCP.

   Полный путь к 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 считывает конфигурацию MCP-серверов из .mcp.json в корне проекта (корне репозитория вашей рабочей области). Для самостоятельно размещённых серверов можно использовать ту же структуру command / args / env, что и в других клиентах. Для удалённой аутентификации на основе токенов Claude Code поддерживает "type": "http" в .mcp.json, в отличие от Claude Desktop.

Настройка с самостоятельно размещённым сервером dbt MCP

подсказка

Клонировать репозиторий dbt-mcp не нужно — для самостоятельного размещения установите uv и запустите uvx dbt-mcp (или используйте конфигурации ниже на этой странице). Клонируйте репозиторий, только если хотите внести вклад в dbt MCP.

1. Следуйте инструкциям в разделе Настройка самостоятельно размещённого MCP, чтобы выбрать способ аутентификации:

   • OAuth с dbt platform
   • Только CLI
   • Переменные окружения (включая файл .env, подключаемый через --env-file)

2. Создайте .mcp.json в корне проекта и добавьте запись dbt в ключ mcpServers верхнего уровня. Выберите вариант, подходящий для вашего сценария использования:

    Самостоятельно размещённый MCP с OAuthStarterEnterpriseEnterprise +

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

   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.

    Самостоятельно размещённый MCP (только CLI)

   Конфигурация для самостоятельного размещения для пользователей, которым нужно только выполнять команды dbt с dbt v1 или dbt v2

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

   Расширенная конфигурация для пользователей, которым нужны собственные переменные окружения. Поместите файл .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):

   {
     "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 (альтернативный вариант):

   {
     "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-адреса.

3. Добавьте запись dbt в .mcp.json, используя вкладку, соответствующую вашему способу аутентификации:

   OAuth (удалённый сервер)

   OAuth для удалённого MCP доступен в публичной бета-версии для учётных записей Starter, Enterprise и Enterprise+.

   Перед подключением

   • Ваш MCP-клиент должен поддерживать OAuth для MCP-серверов, работающих по HTTP. Если такой поддержки нет, используйте аутентификацию на основе токенов.
   • При первом подключении клиент открывает браузер для входа в систему. Затем dbt показывает экран согласия с запрашиваемыми областями доступа (конкретными разрешениями, которые клиенту будет позволено использовать) — описание каждой области доступа см. в разделе Области доступа и согласие.
   • Большинство современных MCP-клиентов регистрируются самостоятельно при первом подключении с помощью динамической регистрации (RFC 7591). Клиенты, которые её не поддерживают, администратор должен зарегистрировать в разделе Account settings → Integrations → App integrations. См. раздел Ручная регистрация.

   Полное описание процесса, сеансов и ограничений см. в разделе OAuth (удалённый MCP).

   Добавьте следующую конфигурацию в .mcp.json в корне проекта. При первом подключении Claude Code откроет браузер для входа и предоставления разрешений.

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

   claude mcp add --transport http dbt https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/

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

   На основе токена

   {
     "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) или сервисный токен с правами Developer для проекта, которому принадлежит среда, указанная в x-dbt-prod-environment-id. Назначьте сервисным токенам набор разрешений Developer. PAT наследуют разрешения своих создателей. Без прав Developer подключение завершается ошибкой 401.
   • x-dbt-prod-environment-id (обязательный) — идентификатор вашей производственной среды dbt platform. Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.
   • x-dbt-dev-environment-id — обязателен для execute_sql и инструментов dbt v2. Пошаговые инструкции см. в разделе Как найти идентификаторы dbt MCP.
   • x-dbt-user-id — обязателен для execute_sql. Подробности см. в разделе Где найти мой идентификатор пользователя?.

   Используйте числовые идентификаторы, а не полные 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). Полный список заголовков см. в разделе Настройка удалённого MCP.

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 с аутентификацией по токену.

Для удалённых подключений ещё раз проверьте, что 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. Для самостоятельно размещённых установок аналогичным образом укажите полный путь к uvx (а также полные пути в --env-file). При удалённом подключении проверьте URL и заголовки, а затем для сравнения попробуйте эквивалентную команду claude mcp add --transport http.

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

Создать GitHub Issue