Hydrolix

官方

Hydrolix 时间序列数据湖集成，为基于LLM的工作流提供模式探索和查询能力。

GitHub

试用此 MCP赞助

你可以用 Hydrolix MCP 做什么？

运行 SQL 查询 — 让您的助手针对您的 Hydrolix 集群执行 run_select_query，可附带可选的单元格限制和用途注释。
列出数据库 — 让您的助手调用 list_databases 来枚举您的 Hydrolix 集群上所有可用的数据库。
探索表结构 — 使用 list_tables 和 get_table_info 来发现表并检索任何数据库的元数据（如结构）。
按时间范围查询 — 请求特定日期范围内按时间戳排序的结果，以利用主键优化实现高效查询。

文档

Hydrolix MCP 服务器

一个用于 Hydrolix 的 MCP 服务器。

快速开始

几分钟内即可启动并运行。本节涵盖 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 启动时不加载您的 shell 的 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（第 2 步中的选项 A），然后运行：

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？

点击本 README 顶部的 Install in VS Code 徽章即可一键安装。如果您更喜欢 UI 流程，请打开命令面板（Cmd+Shift+P / Ctrl+Shift+P），运行 MCP: Add Server，选择 Command (stdio)，并复用第 3 步中的 uvx ... 命令和 env 块。

工具

run_select_query
- 在您的 Hydrolix 集群上执行 SQL 查询。
- 输入：query（字符串）：要执行的 SQL 查询。
- 输入：max_cells（整数，可选）：结果单元格预算（行数 × 列数）；当服务器设置上限时，调用者只能降低它。
- 输入：purpose（字符串，必填）：运行查询的原因；与查询一起记录为 hdx_query_comment。
- 尾部的 FORMAT 子句会被移除；服务器选择传输格式。
list_databases
- 列出您的 Hydrolix 集群上的所有数据库。
list_tables
- 列出数据库中的所有表。
- 输入：database（字符串）：数据库的名称。
get_table_info
- 获取表元数据，如模式（schema）。
- 输入：database（字符串）：数据库的名称。
- 输入：table（字符串）：表的名称。

有效使用

由于 LLM 架构的多样性，并非所有模型都会主动使用上述工具，即使向模型提供了精心构造的工具描述，也很少有模型能在没有指导的情况下有效使用它们。为了在使用 Hydrolix MCP 服务器时获得最佳效果，我们建议：

在提示中按名称引用您的 Hydrolix 数据库并请求使用工具（例如，“使用 MCP 工具访问我的 Hydrolix 数据库，请……”）
- 这鼓励模型使用可用的 MCP 工具并最大限度地减少幻觉。
在提示中包含时间范围（例如，“在 2023 年 12 月 5 日至 2024 年 1 月 18 日之间，……”），并明确要求输出按时间戳排序。
- 这促使模型编写更高效的查询，利用主键优化。

健康检查端点

当使用 HTTP 或 SSE 传输运行时，健康检查端点位于 /health。此端点：

如果服务器健康且能连接到 Hydrolix，则返回 200 OK 以及 Hydrolix 查询头的 Clickhouse 版本
如果服务器无法连接到 Hydrolix 查询头，则返回 503 Service Unavailable

示例：

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

配置

Hydrolix MCP 服务器使用标准的 MCP 服务器条目进行配置。请查阅您的客户端的文档，了解在哪里查找或声明 MCP 服务器的具体说明。下面记录了使用 Claude Desktop 的示例设置。

推荐通过 uv 项目管理器启动 Hydrolix MCP 服务器，它将管理在隔离环境中安装所有其他依赖项。

身份验证

服务器支持多种身份验证方法，优先级如下（从高到低）：

每请求 Bearer 令牌：通过 Authorization: Bearer <token> 头提供的服务账户令牌
每请求 GET 参数：通过 ?token=<token> 查询参数提供的服务账户令牌
基于环境的凭据：通过环境变量配置的凭据
- 服务账户令牌（HYDROLIX_TOKEN），或
- 用户名和密码（HYDROLIX_USER 和 HYDROLIX_PASSWORD）

当配置了多种身份验证方法时，服务器将按上述优先级顺序使用第一个可用的方法。每请求身份验证仅在 HTTP 或 SSE 传输模式下可用。?token= 形式适用于无法发送头的客户端；在部署中，如果每个客户端都发送 Authorization 头，请设置 HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false（请参阅每请求凭据）。

注意：建议使用具有只读角色的服务账户令牌。

使用用户名和密码的 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
向 mcpServers 配置块添加一个 mcp-hydrolix 服务器条目以使用用户名和密码：

{
  "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）

要为 Claude Code 配置 Hydrolix MCP 服务器，请运行以下命令：

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 （推荐）：您的 Hydrolix 集群的规范公共 URL，例如 https://mycluster.hydrolix.live。对于典型的集群外部署，这一个变量就足够了 — 它为 HTTP 查询端点和 REST /version 探测提供主机、端口（方案默认 443/80）和 TLS 设置。
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 服务器的客户端非常有用。

连接到具有每请求身份验证的远程 HTTP 服务器的示例 mcpServers 配置：

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

用于在没有环境凭据的情况下运行您自己的 HTTP 服务器的示例最小 .env 配置：

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

虽然不属于 MCP 规范的一部分，但许多 MCP 客户端允许向 MCP 发出的请求添加头。如果可能，我们建议配置 MCP 客户端通过 Authorization: Bearer <sa-token-here> 头传递服务账户令牌，而不是作为查询参数，以提高安全性。

注意：绑定主机和端口设置仅在传输设置为“http”或“sse”时使用。

可选变量

有关端点覆盖、已弃用的变量别名以及完整的可选调优变量集（超时、查询 SETTINGS 覆盖、结果截断、HTTP/SSE 工作线程调优、代理、指标和逃生舱口），请参阅 docs/CONFIG.md。

维护者

需要操作权限的任务——针对实时 Hydrolix 集群运行端到端测试套件，以及发布版本——在 MAINTAINERS.md 中单独记录。