# Запуск dbt MCP локально

[Назад к гайдам](https://docs.getdbt.tech/guides.md)

[Menu ]()



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

Если вы хотите подключиться к dbt platform с помощью CLI, см. [краткое руководство по OAuth](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-oauth.md).

Чтобы подключиться к dbt Wizard, см. [обзор dbt Wizard](https://docs.getdbt.tech/docs/platform/wizard-overview.md#get-started).

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

Вам не нужно клонировать репозиторий dbt-mcp. Установите [uv](https://docs.astral.sh/uv/getting-started/installation/) и выполните `uvx dbt-mcp` — эта команда загрузит и запустит dbt-mcp.

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

* [Установите uv](https://docs.astral.sh/uv/getting-started/installation/)
* Локальный проект dbt (папка, содержащая файл `dbt_project.yml`)
* Установленный и доступный локально dbt

Полный список переменных окружения и инструкции по включению и отключению наборов инструментов см. в [справочнике переменных окружения](https://docs.getdbt.tech/docs/dbt-ai/mcp-environment-variables.md).

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

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

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

### macOS/Linux

```bash
# 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

```bash
# 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. Вставьте следующую конфигурацию, заменив пути фактическими значениями:

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

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

```shell
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](cursor://anysphere.cursor-deeplink/mcp/install?name=dbt\&config=eyJlbnYiOnsiREJUX1BST0pFQ1RfRElSIjoiL3BhdGgvdG8veW91ci9kYnQvcHJvamVjdCIsIkRCVF9QQVRIIjoiL3BhdGgvdG8veW91ci9kYnQvZXhlY3V0YWJsZSJ9LCJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJkYnQtbWNwIl19)

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

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

```json
{
  "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 работает, ассистент выполнит команду для вашего локального проекта.

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

```bash
uvx dbt-mcp
```

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

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

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

* `dbt run`, `dbt build`, `dbt test`, `dbt compile`, `dbt list`, `dbt parse`, `dbt show`
* Информацию о происхождении и зависимостях моделей и сведения об узлах вашего локального проекта
* Инструменты Codegen (если включены — см. [справочник переменных окружения](https://docs.getdbt.tech/docs/dbt-ai/mcp-environment-variables.md))

Для таких возможностей платформы, как Semantic Layer, Discovery API и запросы к метаданным, требуется учётная запись dbt platform. Чтобы добавить их, см. [Подключение к dbt platform](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-oauth.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`.

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

**Симптомы:** 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).

Все темы по устранению неполадок см. в разделе [Часто задаваемые вопросы о dbt MCP и устранение неполадок](https://docs.getdbt.tech/docs/dbt-ai/mcp-troubleshooting.md).

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

* Добавьте возможности dbt platform: см. [Подключение к dbt platform](https://docs.getdbt.tech/docs/dbt-ai/mcp-quickstart-oauth.md)
* Настройте наборы инструментов или отключите отдельные инструменты: см. [справочник переменных окружения](https://docs.getdbt.tech/docs/dbt-ai/mcp-environment-variables.md)