Hydrolix

официальный

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

GitHub

Попробовать этот MCPСпонсировано

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

Список доступных баз данных — Попросите ассистента перечислить все базы данных в вашем кластере Hydrolix с помощью list_databases.
Просмотр таблиц в базе данных — Запросите список всех таблиц в конкретной базе данных через list_tables.
Проверка схемы таблицы — Получите имена столбцов, типы и метаданные для заданной таблицы с помощью get_table_info.
Выполнение SQL-запросов — Выполните произвольные 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.