Hydrolix MCP Server | Awesome MCP Servers

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 顶部的 在 VS Code 中安装 徽章进行一键安装。如果您更喜欢 UI 流程，请打开命令面板（Cmd+Shift+P / Ctrl+Shift+P），运行 MCP：添加服务器，选择 命令（stdio），并重用第 3 步中的 uvx ... 命令和 env 块。

工具

run_select_query
- 在您的 Hydrolix 集群上执行 SQL 查询。
- 输入：sql（字符串）：要执行的 SQL 查询。
list_databases
- 列出您的 Hydrolix 集群上的所有数据库。
list_tables
- 列出数据库中的所有表。
- 输入：database（字符串）：数据库的名称。
get_table_info
- 获取表元数据，例如模式
- 输入：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 的示例设置。

启动 Hydrolix MCP 服务器的推荐方式是通过 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）

要为 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 是不够的。

端点覆盖

这些覆盖从 HYDROLIX_URL 派生的值。它们对于集群内部署很有用，其中 HTTP 查询端点和版本 API 位于不同的内部主机名或端口。覆盖优先级：显式新变量 > 已弃用的别名 > HYDROLIX_URL 派生 > 硬编码默认值。

HYDROLIX_HTTP_QUERY_HOST / HYDROLIX_HTTP_QUERY_PORT / HYDROLIX_HTTP_QUERY_SECURE：覆盖 ClickHouse HTTP 查询端点。
HYDROLIX_VERSION_API_HOST / HYDROLIX_VERSION_API_PORT / HYDROLIX_VERSION_API_SECURE：覆盖 REST /version 探测端点。默认情况下，HYDROLIX_VERSION_API_SECURE 从已解析的 HTTP 查询安全值继承。

已弃用的变量

以下变量在过渡期内仍然有效，但将在未来版本中移除。请在方便时迁移：

已弃用	替换
`HYDROLIX_HOST`	`HYDROLIX_URL`（首选）或 `HYDROLIX_HTTP_QUERY_HOST`
`HYDROLIX_PORT`	`HYDROLIX_HTTP_QUERY_PORT`
`HYDROLIX_SECURE`	`HYDROLIX_HTTP_QUERY_SECURE`
`HYDROLIX_API_HOST`	`HYDROLIX_VERSION_API_HOST`
`HYDROLIX_API_PORT`	`HYDROLIX_VERSION_API_PORT`

使用这些变量的外部操作员将看到一次性启动警告，建议迁移到 HYDROLIX_URL。集群内（o6r 管理）部署不会看到此警告；它们的迁移由平台处理。

身份验证变量

使用 stdio 传输时，必须至少配置一种身份验证方法：

HYDROLIX_TOKEN：用于基于环境的身份验证的服务账户令牌
HYDROLIX_USER 和 HYDROLIX_PASSWORD：用于基于环境的身份验证的用户名和密码（两者必须一起提供）

总之：

对于 stdio，您必须使用 HYDROLIX_TOKEN 或 HYDROLIX_USER+HYDROLIX_PASS（环境凭证）
对于 http/sse，您可以使用 HYDROLIX_TOKEN 或 HYDROLIX_USER+HYDROLIX_PASS（环境凭证），但也可以改用每请求凭证。

如果未通过环境或请求提供凭证，请求将失败。

可选变量

HYDROLIX_VERIFY：启用/禁用 SSL 证书验证
- 默认值："true"
- 设置为 "false" 可禁用证书验证（不建议在生产环境中使用）
HYDROLIX_DATABASE：要使用的默认数据库
- 默认值：无（使用服务器默认值）
- 设置此项可自动连接到特定数据库
HYDROLIX_MCP_SERVER_TRANSPORT：设置 MCP 服务器的传输方式。
- 默认值："stdio"
- 有效选项："stdio"、"http"、"sse"。这对于使用 MCP Inspector 等工具进行本地开发非常有用。
HYDROLIX_MCP_BIND_HOST：使用 HTTP 或 SSE 传输时，MCP 服务器绑定的主机
- 默认值："127.0.0.1"
- 设置为 "0.0.0.0" 可绑定到所有网络接口（适用于 Docker 或远程访问）
- 仅在传输方式为 "http" 或 "sse" 时使用
HYDROLIX_MCP_BIND_PORT：使用 HTTP 或 SSE 传输时，MCP 服务器绑定的端口
- 默认值："8000"
- 仅在传输方式为 "http" 或 "sse" 时使用
HYDROLIX_MAX_RAW_TIMERANGE：针对非汇总表的查询所允许的最大时间范围（秒）
- 默认值：21600（6 小时）
- 针对汇总表的查询不受此限制影响

对于 MCP Inspector 或使用 HTTP 传输的远程访问：

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_USER=default
HYDROLIX_PASSWORD=myPassword
HYDROLIX_MCP_SERVER_TRANSPORT=http
HYDROLIX_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
HYDROLIX_MCP_BIND_PORT=4200  # Custom port (default: 8000)

使用 HTTP 传输时，服务器将在配置的端口（默认 8000）上运行。例如，使用上述配置：

MCP 端点：http://localhost:4200/mcp
健康检查：http://localhost:4200/health

在 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" 时使用。

端到端测试

tests/e2e/ 下的一个独立套件将本地工作树部署到实时 Hydrolix Kubernetes 集群，并对正在运行的 Pod 进行 MCP 工具的冒烟测试。它被排除在默认测试运行和预推送钩子之外；运行它需要通过 end_to_end pytest 标记显式选择加入，并需要凭据。请参阅 tests/e2e/README.md 获取操作手册。