水力克斯

Name: 水力克斯
Author: hydrolix

作者：hydrolix5 星标更新：2025-11-20

安装使用来源：spider==github.com

项目介绍

Hydrolix MCP Server

Hydrolix 的 MCP 服务器。

工具

run_select_query
- 在您的 Hydrolix 集群上执行 SQL 查询。
- 输入：sql（字符串）：要执行的 SQL 查询。
- 所有 Hydrolix 查询都以 readonly = 1 运行，以确保它们是安全的。
list_databases
- 列出您 Hydrolix 集群上的所有数据库。
list_tables
- 列出数据库中的所有表。
- 输入：database（字符串）：数据库名称。

有效使用

由于 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
# 响应：OK - 已连接到与 ClickHouse 24.3.1 兼容的 Hydrolix

配置

Hydrolix MCP 服务器使用标准的 MCP 服务器条目进行配置。请参阅客户端文档以获取有关在哪里找到或声明 MCP 服务器的具体说明。下面记录了一个使用 Claude Desktop 的示例设置。

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

使用用户名和密码的 MCP 服务器定义（JSON）：

{
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp-hydrolix",
    "--python",
    "3.13",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_HOST": "<hydrolix-host>",
    "HYDROLIX_USER": "<hydrolix-user>",
    "HYDROLIX_PASSWORD": "<hydrolix-password>"
  }
}

使用服务账户令牌的 MCP 服务器定义（JSON）：

{
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp-hydrolix",
    "--python",
    "3.13",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_HOST": "<hydrolix-host>",
    "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
  }
}

使用用户名和密码的 MCP 服务器定义（YAML）：

command: uv
args:
- run
- --with
- mcp-hydrolix
- --python
- "3.13"
- mcp-hydrolix
env:
  HYDROLIX_HOST: <hydrolix-host>
  HYDROLIX_USER: <hydrolix-user>
  HYDROLIX_PASSWORD: <hydrolix-password>

使用服务账户令牌的 MCP 服务器定义（YAML）：

command: uv
args:
- run
- --with
- mcp-hydrolix
- --python
- "3.13"
- mcp-hydrolix
env:
  HYDROLIX_HOST: <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": "uv",
      "args": [
        "run",
        "--with",
        "mcp-hydrolix",
        "--python",
        "3.13",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_HOST": "<hydrolix-host>",
        "HYDROLIX_USER": "<hydrolix-user>",
        "HYDROLIX_PASSWORD": "<hydrolix-password>"
      }
    }
  }
}

要利用服务账户，请使用以下配置块：

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-hydrolix",
        "--python",
        "3.13",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_HOST": "<hydrolix-host>",
        "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
      }
    }
  }
}

更新环境变量定义以指向您的 Hydrolix 集群。
（推荐）找到 uv 命令条目，并将其替换为 uv 可执行文件的绝对路径。这确保了在启动服务器时使用正确的 uv 版本。您可以使用 which uv 或 where.exe uv 查找该路径。
重启 Claude Desktop 应用更改。如果您使用的是 Windows，请确保通过系统托盘图标完全关闭客户端。

配置示例（Claude Code）

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

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_USER=<hydrolix-user> \
  --env HYDROLIX_PASSWORD=<hydrolix-password> \
  --env HYDROLIX_HOST=<hydrolix-host> \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uv run --with mcp-hydrolix --python 3.13 mcp-hydrolix

环境变量

以下变量用于配置 Hydrolix 连接。这些变量可以通过 MCP 配置块（如上所示）、.env 文件或传统环境变量提供。

必需变量

HYDROLIX_HOST：您的 Hydrolix 服务器主机名
HYDROLIX_TOKEN：Hydrolix 服务账户令牌（如果使用用户名/密码则省略）
HYDROLIX_USER：身份验证用户名（如果使用服务账户则省略）
HYDROLIX_PASSWORD：身份验证密码（如果使用服务账户则省略）

认证优先级：如果同时提供了 HYDROLIX_TOKEN 和 HYDROLIX_USER/HYDROLIX_PASSWORD，服务账户令牌优先，用户名/密码身份验证将被忽略。

可选变量

HYDROLIX_PORT：您的 Hydrolix 服务器端口号
- 默认值：8088
- 除非使用非标准端口，否则通常不需要设置。
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" 时使用

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

HYDROLIX_HOST=localhost
HYDROLIX_USER=default
HYDROLIX_PASSWORD=myPassword
HYDROLIX_MCP_SERVER_TRANSPORT=http
HYDROLIX_MCP_BIND_HOST=0.0.0.0  # 绑定到所有接口
HYDROLIX_MCP_BIND_PORT=4200  # 自定义端口（默认：8000）

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

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

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