Запуск самостоятельно размещённого сервера dbt MCP

Это краткое руководство поможет вам подключить сервер dbt MCP к локальному проекту dbt. Такая настройка позволит вашему ИИ-ассистенту использовать инструменты команд dbt (run, build, test, compile и другие).

Если вы хотите подключиться к dbt platform с помощью CLI, см. краткое руководство по OAuth.

Чтобы подключиться к dbt Wizard, см. обзор dbt Wizard.

Клонировать репозиторий не нужно

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

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

• Установите uv
• Локальный проект dbt (папка, содержащая файл dbt_project.yml)
• Установленный и доступный локально dbt

Полный список переменных окружения и инструкции по включению и отключению наборов инструментов см. в справочнике переменных окружения.

Шаг 1. Определите пути

Перед настройкой MCP-клиента вам понадобятся два значения:

• DBT_PROJECT_DIR — полный путь к папке вашего проекта dbt (где находится dbt_project.yml). Например, если ваш проект называется jaffle_shop, путь должен быть /Users/yourname/dbt-projects/jaffle_shop.
• DBT_PATH — полный путь к исполняемому файлу dbt.

macOS/Linux

# Find DBT_PATH
which dbt
# Example output: /opt/homebrew/bin/dbt

# Find DBT_PROJECT_DIR — run from inside your project folder
pwd
# Example output: /Users/yourname/projects/my_dbt_project

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

Windows

# Find DBT_PATH
where dbt
# Example output: C:\Python39\Scripts\dbt.exe

# Find DBT_PROJECT_DIR — run from inside your project folder
cd
# Example output: C:\Users\yourname\projects\my_dbt_project

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

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

Шаг 2. Добавьте сервер в MCP-клиент

Замените пути ниже значениями из шага 1:

Claude Desktop

1. В Claude Desktop перейдите в Settings → вкладка Developer → Edit Config.
2. Вставьте следующую конфигурацию, заменив пути фактическими значениями:

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

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

3. Сохраните изменения и перезапустите Claude Desktop.

Расположение файла конфигурации:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

Выполните эту команду, заменив пути фактическими значениями:

claude mcp add dbt \
-e DBT_PROJECT_DIR=/path/to/your/dbt/project \
-e DBT_PATH=/path/to/your/dbt/executable \
-- uvx dbt-mcp

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

Cursor

Откройте Cursor и нажмите ссылку ниже для автоматической настройки:

Добавить dbt v1 или dbt v2 в Cursor

После нажатия:

1. Укажите в DBT_PROJECT_DIR полный путь к вашему проекту dbt.
2. Укажите в DBT_PATH полный путь к исполняемому файлу dbt (из шага 1).
3. Сохраните конфигурацию.

VS Code

1. Откройте Settings → Features → Chat и убедитесь, что MCP включён.
2. Откройте палитру команд (Ctrl/Cmd + Shift + P) и выберите MCP: Open User Configuration.
3. Добавьте следующую конфигурацию в mcp.json, заменив пути фактическими значениями:

VS Code использует "servers", а не "mcpServers"

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

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

4. Сохраните файл.

Шаг 3. Проверьте настройку

Попросите ИИ-ассистента выполнить команду dbt (например, «Выполни dbt compile для моего проекта» или «Выведи список всех моделей в моём проекте»). Если dbt MCP работает, ассистент выполнит команду для вашего локального проекта.

 Необязательно: проверка из командной строки

uvx dbt-mcp

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

Если ошибок нет, конфигурация верна. Нажмите Ctrl+C, чтобы остановить сервер.

Доступные возможности

При настройке только через CLI ваш ИИ-ассистент может использовать:

• dbt run, dbt build, dbt test, dbt compile, dbt list, dbt parse, dbt show
• Информацию о происхождении и зависимостях моделей и сведения об узлах вашего локального проекта
• Инструменты Codegen (если включены — см. справочник переменных окружения)

Для таких возможностей платформы, как Semantic Layer, Discovery API и запросы к метаданным, требуется учётная запись dbt platform. Чтобы добавить их, см. Подключение к dbt platform.

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

Не удаётся найти исполняемый файл 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.

Сервер не запускается

Симптомы: 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 — убедитесь, что указанные пути существуют и являются абсолютными.
• Недействительные токены аутентификации или токены с истёкшим сроком действия — создайте новый токен и обновите конфигурацию.
• Отсутствие обязательных переменных окружения для набора инструментов, который вы пытаетесь использовать — см. Требования инструментов.

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

Дальнейшие шаги

• Добавьте возможности dbt platform: см. Подключение к dbt platform
• Настройте наборы инструментов или отключите отдельные инструменты: см. справочник переменных окружения

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

Создать GitHub Issue