Hydrolix MCP Server

Name: Hydrolix MCP Server
Author: hydrolix

本地服务

github.com/hydrolix数据库111 周前更新

代码仓库

关于 Hydrolix MCP Server

Hydrolix MCP Server 将 MCP 客户端连接到 Hydrolix 集群，以执行 SQL 查询并获取数据库元数据。它提供数据库和表列表、架构查看及查询工具。

主要功能

01执行 SQL 查询
02列出集群数据库
03列出数据库中的表
04获取表架构元数据
05支持令牌与凭据认证

适用场景

01浏览 Hydrolix 集群中的数据库
02查询前检查表架构
03执行带用途记录的 SQL 查询
04通过 HTTP 或 SSE 使用单请求凭据连接

MCP 相关

向 MCP 客户端提供查询 Hydrolix 以及获取数据库、表和架构信息的工具，并支持 stdio、HTTP 和 SSE 传输。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "hydrolix": {
      "command": "uvx",
      "args": [
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_HOST": "<HYDROLIX_HOST>",
        "HYDROLIX_TOKEN": "<HYDROLIX_TOKEN>",
        "HYDROLIX_USER": "<HYDROLIX_USER>",
        "HYDROLIX_PASSWORD": "<HYDROLIX_PASSWORD>"
      }
    }
  }
}

启动命令uvx mcp-hydrolix

需要配置的环境变量

HYDROLIX_HOSTThe hostname of your Hydrolix server

HYDROLIX_TOKEN密钥Service account token(alternative to username/password)

HYDROLIX_USERHydrolix username (use with HYDROLIX_PASSWORD)

HYDROLIX_PASSWORD密钥Hydrolix password (use with HYDROLIX_USER)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypimcp-hydrolix0.2.3stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

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> 替换为你的实际凭据。

说明

如果你使用的是选项 B（pip），请使用 "command": "mcp-hydrolix"，且不要添加 "args" 字段。

提示

如果文件中已有其他条目，请将 "mcp-hydrolix" 块添加到现有的 "mcpServers" 对象中，而不是替换整个文件。

说明

如果你使用服务账号令牌而不是用户名和密码进行身份验证，请参阅身份验证。

找不到命令？

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（选项 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？

点击本 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
- 获取表元数据，例如架构。
- 输入：database（字符串）：数据库名称。
- 输入：table（字符串）：表名称。

有效使用

由于大模型架构种类繁多，并非所有模型都会主动使用上述工具；即使为模型提供了精心编写的工具描述，也很少有模型能在没有指导的情况下有效使用这些工具。为了在使用 Hydrolix MCP 服务时获得最佳效果，我们建议：

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

健康检查端点

使用 HTTP 或 SSE 传输时，可通过 /health 使用健康检查端点。此端点：

如果服务运行正常且能够连接到 Hydrolix，则返回带有 Hydrolix 查询头 Clickhouse 版本的 200 OK
如果服务无法连接到 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（参阅单次请求凭据）。

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

使用用户名和密码的 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 集群。

4.（推荐）找到 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 中的文档。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。