Hydrolix

официальный

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

GitHub

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

Выполнение SQL-запросов — Попросите вашего ассистента выполнить run_select_query для вашего кластера Hydrolix, с опциональными ограничениями по количеству строк и комментарием о цели запроса.
Список баз данных — Попросите ассистента вызвать list_databases, чтобы перечислить все базы данных, доступные в вашем кластере Hydrolix.
Изучение схем таблиц — Используйте list_tables и get_table_info, чтобы обнаружить таблицы и получить метаданные, такие как схема, для любой базы данных.
Запросы с временными диапазонами — Запрашивайте результаты, упорядоченные по времени, в пределах конкретных диапазонов дат, чтобы использовать оптимизации первичного ключа для эффективных запросов.

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

Сервер MCP Hydrolix

Сервер 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-сервер успешно подключен.
Попробуйте этот запрос, чтобы убедиться, что все работает:

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

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 и протестируйте с тем же запросом:

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

Предпочитаете VS Code?

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

Инструменты

run_select_query
- Выполнение SQL-запросов к вашему кластеру Hydrolix.
- Вход: query (строка): SQL-запрос для выполнения.
- Вход: max_cells (целое число, необязательно): Бюджет ячеек результата (строки × столбцы); когда сервер устанавливает предел, вызывающий может только снизить его.
- Вход: purpose (строка, обязательно): Причина выполнения запроса; записывается вместе с запросом как hdx_query_comment.
- Завершающее предложение FORMAT удаляется; сервер выбирает формат передачи.
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 транспорта. Форма ?token= существует для клиентов, которые не могут отправлять заголовки; установите HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false на развертываниях, где каждый клиент отправляет заголовок Authorization (см. Учетные данные для каждого запроса).

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

Определение 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 для переопределений конечных точек, устаревших псевдонимов переменных и полного набора необязательных переменных настройки (таймауты, переопределения настроек запросов, усечение результатов, настройка рабочих процессов HTTP/SSE, прокси, метрики и запасные варианты).

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

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