Hydrolix

официальный

Интеграция с временным даталэйком Hydrolix, обеспечивающая исследование схем и возможности запросов для рабочих процессов на основе LLM.

GitHub

Что можно делать с Hydrolix MCP?

List all databases — Попросите ассистента перечислить все базы данных в вашем кластере Hydrolix с помощью list_databases.
List tables in a database — Получите все имена таблиц в конкретной базе данных через list_tables.
Get table schema and metadata — Просмотрите имена столбцов, типы и другие метаданные для заданной таблицы с помощью get_table_info.
Run ad-hoc SQL queries — Выполните произвольные SQL-запросы к вашему кластеру Hydrolix, используя run_select_query, например, для фильтрации логов по временному диапазону.

Документация

Hydrolix MCP-сервер

MCP-сервер для Hydrolix.

Быстрый старт

Начните работу за несколько минут. В этом разделе рассматриваются Claude Desktop и Claude Code.

Шаг 1 — Подготовка

Перед началом убедитесь, что у вас есть:

Учетные данные Hydrolix — имя хоста вашего кластера, а также имя пользователя/пароль или токен сервисной учетной записи. Если у вас их нет, обратитесь к администратору Hydrolix.
Claude Desktop — скачайте с claude.ai/download.

Шаг 2 — Установка MCP-сервера

Выберите способ, соответствующий вашей конфигурации:

Вариант A: Использование uv (рекомендуется)

uv автоматически управляет Python и загружает mcp-hydrolix по требованию, поэтому отдельный шаг установки не требуется. Если у вас нет uv, установите его:

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Вариант B: Использование pip

Требуется Python 3.13+. Если вам нужно установить Python, скачайте его с python.org.

pip install mcp-hydrolix

Шаг 3 — Настройка Claude Desktop

Откройте файл конфигурации Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Добавьте следующую запись в объект "mcpServers" (создайте файл с этим содержимым, если он еще не существует):

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<your-hydrolix-hostname>",
        "HYDROLIX_USER": "<your-username>",
        "HYDROLIX_PASSWORD": "<your-password>"
      }
    }
  }
}

Замените <your-hydrolix-hostname>, <your-username> и <your-password> вашими реальными учетными данными.

[!NOTE] Если вы использовали вариант B (pip), используйте "command": "mcp-hydrolix" без поля "args".

[!TIP] Если в файле уже есть другие записи, добавьте блок "mcp-hydrolix" внутрь существующего объекта "mcpServers", а не заменяйте весь файл.

[!NOTE] Если вы аутентифицируетесь с помощью токена сервисной учетной записи вместо имени пользователя/пароля, см. Аутентификация.

Команда не найдена?

Claude Desktop запускается без PATH вашей оболочки, поэтому он может не найти исполняемый файл, даже если он установлен. Найдите полный путь и используйте его в качестве значения "command" в конфигурации.

Вариант A (uv): найти uvx:

macOS / Linux: which uvx
Windows: where.exe uvx

Вариант B (pip): найти mcp-hydrolix:

macOS / Linux: which mcp-hydrolix
Windows: where.exe mcp-hydrolix

Если which/where.exe ничего не возвращает, исполняемый файл отсутствует в вашем PATH. Самое простое решение — перейти на вариант A (uv), который управляет окружением Python и PATH за вас.

Шаг 4 — Перезапустите Claude Desktop

Перезапустите приложение, чтобы применить конфигурацию.

Пользователи macOS / Windows: Обязательно полностью закройте Claude перед перезапуском. На macOS нажмите Cmd+Q или щелкните правой кнопкой мыши значок в Dock и выберите «Завершить». В Windows используйте значок в системном трее.

Шаг 5 — Проверьте работу

Откройте новый диалог в Claude Desktop. Найдите значок инструментов/молотка рядом с полем ввода текста — это подтверждает, что MCP-сервер успешно подключился.
Попробуйте следующий запрос, чтобы убедиться, что все работает:

Используя инструменты Hydrolix MCP, выведи список доступных баз данных.

Claude должен вызвать инструмент list_databases и вернуть список баз данных из вашего кластера.

Используете Claude Code?

Если вы предпочитаете командную строку, убедитесь, что uv установлен (вариант A из Шага 2), затем выполните:

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_URL=https://<your-hydrolix-hostname> \
  --env HYDROLIX_USER=<your-username> \
  --env HYDROLIX_PASSWORD=<your-password> \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

Затем откройте Claude Code и протестируйте с тем же запросом:

Используя инструменты Hydrolix MCP, выведи список доступных баз данных.

Используете VS Code?

Нажмите на значок Установить в VS Code в верхней части этого README для установки в один клик. Если вы предпочитаете интерфейс, откройте палитру команд (Cmd+Shift+P / Ctrl+Shift+P), выполните MCP: Add Server, выберите Command (stdio) и повторно используйте команду uvx ... и блок env из Шага 3.

Инструменты

run_select_query
- Выполнение SQL-запросов в вашем кластере Hydrolix.
- Входные данные: sql (строка): SQL-запрос для выполнения.
list_databases
- Вывод списка всех баз данных в вашем кластере Hydrolix.
list_tables
- Вывод списка всех таблиц в базе данных.
- Входные данные: database (строка): Имя базы данных.
get_table_info
- Получение метаданных таблицы, таких как схема.
- Входные данные: database (строка): Имя базы данных.
- Входные данные: table (строка): Имя таблицы.

Эффективное использование

Из-за большого разнообразия архитектур LLM не все модели будут активно использовать указанные выше инструменты, и лишь немногие будут делать это эффективно без руководства, даже с тщательно составленными описаниями инструментов, предоставленными модели. Чтобы получить наилучшие результаты от вашей модели при использовании MCP-сервера Hydrolix, мы рекомендуем следующее:

Обращайтесь к вашей базе данных Hydrolix по имени и запрашивайте использование инструментов в ваших запросах (например, «Используя инструменты MCP для доступа к моей базе данных Hydrolix, пожалуйста, ...»)
- Это побуждает модель использовать доступные инструменты MCP и минимизирует галлюцинации.
Включайте временные диапазоны в ваши запросы (например, «В период с 5 декабря 2023 г. по 18 января 2024 г. ...») и специально запрашивайте, чтобы вывод был упорядочен по временной метке.
- Это побуждает модель писать более эффективные запросы, использующие оптимизации первичного ключа.

Конечная точка проверки работоспособности

При работе с транспортом HTTP или SSE конечная точка проверки работоспособности доступна по адресу /health. Эта конечная точка:

Возвращает 200 OK с версией Clickhouse головного узла запросов Hydrolix, если сервер работоспособен и может подключиться к Hydrolix.
Возвращает 503 Service Unavailable, если сервер не может подключиться к головному узлу запросов Hydrolix.

Пример:

curl http://localhost:8000/health
# Response: OK - Connected to Hydrolix compatible with ClickHouse 24.3.1

Конфигурация

MCP-сервер Hydrolix настраивается с использованием стандартной записи MCP-сервера. Инструкции о том, где найти или объявить MCP-серверы, смотрите в документации вашего клиента. Пример настройки с использованием Claude Desktop описан ниже.

Рекомендуемый способ запуска MCP-сервера Hydrolix — через менеджер проектов uv, который будет управлять установкой всех остальных зависимостей в изолированном окружении.

Аутентификация

Сервер поддерживает несколько методов аутентификации со следующим приоритетом (от высшего к низшему):

Токен Bearer для каждого запроса: Токен сервисной учетной записи, предоставленный через заголовок Authorization: Bearer <token>.
GET-параметр для каждого запроса: Токен сервисной учетной записи, предоставленный через параметр запроса ?token=<token>.
Учетные данные на основе окружения: Учетные данные, настроенные через переменные окружения.
- Токен сервисной учетной записи (HYDROLIX_TOKEN), или
- Имя пользователя и пароль (HYDROLIX_USER и HYDROLIX_PASSWORD)

Если настроено несколько методов аутентификации, сервер будет использовать первый доступный метод в указанном выше порядке приоритета. Аутентификация для каждого запроса доступна только при использовании режимов транспорта HTTP или SSE.

Примечание: Рекомендуется использовать токен сервисной учетной записи с ролью только для чтения.

Определение MCP-сервера с использованием имени пользователя и пароля (JSON):

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_USER": "<hydrolix-user>",
    "HYDROLIX_PASSWORD": "<hydrolix-password>"
  }
}

Определение MCP-сервера с использованием токена сервисной учетной записи (JSON):

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
  }
}

Определение MCP-сервера с использованием имени пользователя и пароля (YAML):

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_URL: https://<hydrolix-host>
  HYDROLIX_USER: <hydrolix-user>
  HYDROLIX_PASSWORD: <hydrolix-password>

Определение MCP-сервера с использованием токена сервисной учетной записи (YAML):

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_URL: https://<hydrolix-host>
  HYDROLIX_TOKEN: <hydrolix-service-account-token>

Пример конфигурации (Claude Desktop)

Откройте файл конфигурации Claude Desktop, расположенный по адресу:
- В macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- В Windows: %APPDATA%/Claude/claude_desktop_config.json
Добавьте запись сервера mcp-hydrolix в блок конфигурации mcpServers для использования имени пользователя и пароля:

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<hydrolix-host>",
        "HYDROLIX_USER": "<hydrolix-user>",
        "HYDROLIX_PASSWORD": "<hydrolix-password>"
      }
    }
  }
}

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

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<hydrolix-host>",
        "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
      }
    }
  }
}

Обновите определения переменных окружения, чтобы они указывали на ваш кластер Hydrolix.
(Рекомендуется) Найдите запись команды для uvx и замените ее абсолютным путем к исполняемому файлу uvx. Это гарантирует, что при запуске сервера будет использоваться правильная версия uvx. Вы можете найти этот путь с помощью which uvx или where.exe uvx.
Перезапустите Claude Desktop, чтобы применить изменения. Если вы используете Windows, убедитесь, что Claude полностью остановлен, закрыв клиент через значок в системном трее.

Пример конфигурации (Claude Code)

Чтобы настроить MCP-сервер Hydrolix для Claude Code, выполните следующую команду:

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_USER=<hydrolix-user> \
  --env HYDROLIX_PASSWORD=<hydrolix-password> \
  --env HYDROLIX_URL=https://<hydrolix-host> \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

Переменные окружения

Следующие переменные используются для настройки подключения к Hydrolix. Эти переменные могут быть предоставлены через блок конфигурации MCP (как показано выше), файл .env или традиционные переменные окружения.

Обязательные переменные

Вы ДОЛЖНЫ установить одну из следующих переменных для идентификации кластера:

HYDROLIX_URL (рекомендуется): Канонический публичный URL вашего кластера Hydrolix, например, https://mycluster.hydrolix.live. Для типичных развертываний вне кластера этой единственной переменной достаточно — она предоставляет хост, порт (по умолчанию для схемы 443/80) и настройки TLS как для конечной точки HTTP-запросов, так и для проверки REST /version.
HYDROLIX_HOST (устарело): Имя хоста вашего сервера Hydrolix. По-прежнему поддерживается для обратной совместимости, но должно быть заменено на HYDROLIX_URL.

Когда HYDROLIX_MCP_SERVER_TRANSPORT имеет значение http или sse, HYDROLIX_URL особенно требуется (конечная точка метаданных OAuth объявляет ее). Одного HYDROLIX_HOST недостаточно для этих транспортов.

Переменные аутентификации

При использовании транспорта stdio должен быть настроен хотя бы один метод аутентификации:

HYDROLIX_TOKEN: Токен сервисной учетной записи для аутентификации на основе окружения.
HYDROLIX_USER и HYDROLIX_PASSWORD: Имя пользователя и пароль для аутентификации на основе окружения (должны быть предоставлены вместе).

В итоге:

Для stdio вы ДОЛЖНЫ использовать HYDROLIX_TOKEN или HYDROLIX_USER+HYDROLIX_PASS (учетные данные окружения).
Для http/sse вы МОЖЕТЕ использовать HYDROLIX_TOKEN или HYDROLIX_USER+HYDROLIX_PASS (учетные данные окружения), но вместо этого вы можете использовать учетные данные для каждого запроса.

Если учетные данные не предоставлены ни через окружение, ни в запросе, запрос завершится ошибкой.

Использование аутентификации для каждого запроса с транспортом HTTP

При использовании транспорта HTTP или SSE вы можете опустить учетные данные на основе окружения и вместо этого предоставлять аутентификацию для каждого запроса. Это полезно для многопользовательских сценариев или с клиентами, которые не поддерживают локальный запуск MCP-серверов.

Пример конфигурации mcpServers для подключения к удаленному HTTP-серверу с аутентификацией для каждого запроса:

{
  "mcpServers": {
    "mcp-hydrolix-remote": {
      "url": "https://my-hydrolix-mcp.example.com/mcp?token=<service-account-token>"
    }
  }
}

Пример минимальной конфигурации .env для запуска собственного HTTP-сервера без учетных данных окружения:

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_MCP_SERVER_TRANSPORT=http

Хотя это не является частью спецификации MCP, многие MCP-клиенты позволяют добавлять заголовки к запросам, отправляемым MCP. Когда это возможно, мы рекомендуем настроить MCP-клиент для передачи токена сервисной учетной записи через заголовок Authorization: Bearer <sa-token-here> вместо параметра запроса для большей безопасности.

Примечание: Настройки хоста и порта привязки используются только тогда, когда транспорт установлен как «http» или «sse».

Необязательные переменные

См. docs/CONFIG.md для получения информации о переопределении конечных точек, устаревших псевдонимах переменных и полном наборе необязательных переменных настройки (тайм-ауты, переопределения SETTINGS запросов, усечение результатов, настройка рабочих процессов HTTP/SSE, прокси, метрики и аварийные люки).

Сопровождающие

Задачи, требующие операционных привилегий — запуск полного набора тестов на действующем кластере Hydrolix и выпуск релиза — описаны отдельно в MAINTAINERS.md.