Hydrolix MCP服务器

](https://pypi.org/project/mcp-hydrolix) ![Install in VS Code](https://vscode.dev/redirect/mcp/install?name=mcp-hydrolix&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--python%22%2C%223.13%22%2C%22--refresh-package%22%2C%22mcp-hydrolix%22%2C%22mcp-hydrolix%22%5D%2C%22env%22%3A%7B%22HYDROLIX_HOST%22%3A%22%24%7Binput%3Ahydrolix_host%7D%22%2C%22HYDROLIX_USER%22%3A%22%24%7Binput%3Ahydrolix_user%7D%22%2C%22HYDROLIX_PASSWORD%22%3A%22%24%7Binput%3Ahydrolix_password%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22hydrolix_host%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Hydrolix%20hostname%20%28e.g.%20mycluster.hydrolix.live%29%22%7D%2C%7B%22id%22%3A%22hydrolix_user%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Hydrolix%20username%22%7D%2C%7B%22id%22%3A%22hydrolix_password%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Hydrolix%20password%22%2C%22password%22%3Atrue%7D%5D) ![Install in VS Code Insiders](https://insiders.vscode.dev/redirect/mcp/install?name=mcp-hydrolix&quality=insiders&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--python%22%2C%223.13%22%2C%22--refresh-package%22%2C%22mcp-hydrolix%22%2C%22mcp-hydrolix%22%5D%2C%22env%22%3A%7B%22HYDROLIX_HOST%22%3A%22%24%7Binput%3Ahydrolix_host%7D%22%2C%22HYDROLIX_USER%22%3A%22%24%7Binput%3Ahydrolix_user%7D%22%2C%22HYDROLIX_PASSWORD%22%3A%22%24%7Binput%3Ahydrolix_password%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22hydrolix_host%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Hydrolix%20hostname%20%28e.g.%20mycluster.hydrolix.live%29%22%7D%2C%7B%22id%22%3A%22hydrolix_user%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Hydrolix%20username%22%7D%2C%7B%22id%22%3A%22hydrolix_password%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Hydrolix%20password%22%2C%22password%22%3Atrue%7D%5D)

Hydrolix的MCP服务器。

快速入门

几分钟后起床跑步。本节介绍克劳德桌面和克劳德代码。

第一步——先决条件

在开始之前，请确保您已经：

Hydrolix证书 --集群主机名加上用户名/密码或服务帐户令牌。如果您没有这些，请咨询您的Hydrolix管理员。
克劳德桌面版 --下载自 claude.ai/下载.

步骤2--安装MCP服务器

选择与您的设置相匹配的方法：

选项A：使用紫外线（推荐）

紫外线自动管理Python并按需下载mcp-hydrolix，因此不需要单独的安装步骤。如果你没有紫外线，请安装它：

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桌面

打开Claude Desktop配置文件：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

将以下条目添加到 "mcpServers" object（如果此内容尚不存在，则创建包含此内容的文件）：

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_HOST": "",
        "HYDROLIX_USER": "",
        "HYDROLIX_PASSWORD": ""
      }
    }
  }
}

替换 `, ，以及 ` 凭你的真实证件。

\[！注意\] 如果您使用选项B（pip），请使用 "command": "mcp-hydrolix" 没有 "args" 取而代之的是现场。

\[！提示\] 如果文件已经有其他条目，请添加 "mcp-hydrolix" 现有内部的块 "mcpServers" 对象，而不是替换整个文件。

\[！注意\] 如果您使用服务帐户令牌而不是用户名/密码进行身份验证，请参阅认证.

Command not found?

Claude Desktop在没有shell的PATH的情况下启动，因此即使安装了二进制文件，它也可能找不到。找到完整路径并将其用作 "command" 配置中的值。

选项A（紫外线）： 找到 uvx:

macOS/Linux： which uvx
窗户： where.exe uvx

选项B（点）： 找到 mcp-hydrolix:

macOS/Linux： which mcp-hydrolix
窗户： where.exe mcp-hydrolix

如果 which/where.exe 不返回任何值，二进制文件不在您的PATH中。最干净的修复方法是切换到选项A（uv），它为您管理Python环境和PATH。

步骤4--重新启动克劳德桌面

重新启动应用程序以应用配置。

macOS/Windows用户： 请确保在重新启动之前完全退出Claude。在macOS上，按Cmd+Q或右键单击Dock图标并选择Quit。在Windows上，使用系统托盘图标。

第5步——验证它是否正常工作

在Claude Desktop中打开新对话。在文本输入附近寻找工具/锤子图标——这确认MCP服务器已成功连接。

尝试此提示以确认一切正常：

> 使用Hydrolix MCP工具，列出可用的数据库。

克劳德应该打电话给 list_databases 工具并返回集群中的数据库列表。

______________________________________________________________________

使用克劳德代码？

如果您更喜欢命令行，请确保安装了uv（选项A 步骤2)，然后运行：

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_HOST= \
  --env HYDROLIX_USER= \
  --env HYDROLIX_PASSWORD= \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

然后打开Claude Code并使用相同的提示进行测试：

使用Hydrolix MCP工具，列出可用的数据库。

使用VS代码？

点击 在VS代码中安装 此README顶部的徽章用于一键安装。如果您更喜欢UI流，请打开命令选项板(Cmd+Shift+P / Ctrl+Shift+P)，跑 MCP：添加服务器，选择 命令（stdio），并重复使用 uvx ... 命令和 env 阻止步骤3.

工具

run_select_query

- 在Hydrolix集群上执行SQL查询。 - 输入： sql （string）：要执行的SQL查询。

list_databases

- 列出Hydrolix集群上的所有数据库。

list_tables

- 列出数据库中的所有表。 - 输入： database （string）：数据库的名称。

get_table_info

- 获取表元数据，如架构 - 输入： database （string）：数据库的名称。 - 输入： table （string）：表的名称。

有效使用

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

按名称参考您的Hydrolix数据库，并在提示中请求工具使用（例如，“请使用MCP工具访问我的Hydroix数据库…”）

- 这鼓励模型使用可用的MCP工具，并最大限度地减少幻觉。

在提示中包含时间范围（例如，“2023年12月5日至2024年1月18日之间，…”），并特别要求按时间戳对输出进行排序。

- 这促使模型编写更高效的查询，以利用主键优化

健康检查端点

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

退货 200 OK 如果服务器运行正常并且可以连接到Hydrolix，则使用Hydrolix查询头的Clickhouse版本
退货 503 Service Unavailable 如果服务器无法连接到Hydrolix查询头

例子：

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 项目经理，它将管理在隔离环境中安装所有其他依赖项。

认证

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

按请求承载令牌：通过提供的服务帐户令牌 Authorization: Bearer 头球
按请求GET参数：通过提供的服务帐户令牌 ?token= 查询参数
基于环境的凭据：通过环境变量配置凭据

- 服务帐户令牌(HYDROLIX_TOKEN)，或 - 用户名和密码(HYDROLIX_USER 和 HYDROLIX_PASSWORD)

当配置了多种身份验证方法时，服务器将使用上述优先级顺序中的第一种可用方法。仅当使用HTTP或SSE传输模式时，才可进行按请求身份验证。

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

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

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_HOST": "",
    "HYDROLIX_USER": "",
    "HYDROLIX_PASSWORD": ""
  }
}

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

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_HOST": "",
    "HYDROLIX_TOKEN": ""
  }
}

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

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_HOST: 
  HYDROLIX_USER: 
  HYDROLIX_PASSWORD:

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

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_HOST: 
  HYDROLIX_TOKEN:

配置示例（克劳德桌面）

打开位于以下位置的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_HOST": "",
        "HYDROLIX_USER": "",
        "HYDROLIX_PASSWORD": ""
      }
    }
  }
}

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

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_HOST": "",
        "HYDROLIX_TOKEN": ""
      }
    }
  }
}

更新环境变量定义以指向Hydrolix集群。

（推荐）找到以下命令项 uvx 并将其替换为指向的绝对路径 uvx 可执行。这确保了正确的版本 uvx 启动服务器时使用。您可以使用以下命令找到此路径 which uvx 或 where.exe uvx.

重新启动Claude Desktop以应用更改。如果您使用的是Windows，请使用系统托盘图标关闭客户端，确保完全停止Claude。

配置示例（克劳德代码）

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

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_USER= \
  --env HYDROLIX_PASSWORD= \
  --env HYDROLIX_HOST= \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

环境变量

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

必需变量

HYDROLIX_HOST：Hydrolix服务器的主机名

身份验证变量

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

HYDROLIX_TOKEN：用于基于环境的身份验证的服务帐户令牌
HYDROLIX_USER 和 HYDROLIX_PASSWORD：用于基于环境的身份验证的用户名和密码（必须同时提供）

总之：

对于stdio，您必须使用HYDROLIX_TOKEN或HYDROLIZ_USER+HYDROLIS_PASS（环境证书）
对于http/sse，您可以使用HYDROLIX_TOKEN或HYDROLIO_USER+HYDROLIZ.PASS（环境凭据），但也可以使用按请求凭据。

如果没有通过环境或请求提供凭据，则请求将失败。

可选变量

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"

HYDROLIX_MAX_RAW_TIMERANGE：对非汇总表的查询允许的最大时间范围（秒）

- 违约： 21600 （6小时） - 针对汇总表的查询不受此限制的影响

对于MCP检查器或使用HTTP传输的远程访问：

HYDROLIX_HOST=localhost
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服务器的客户端非常有用。

示例 mcpServers 使用按请求身份验证连接到远程HTTP服务器的配置：

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

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

HYDROLIX_HOST=my-cluster.hydrolix.net
HYDROLIX_MCP_SERVER_TRANSPORT=http

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

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

端到端测试

独立套房 tests/e2e/ 将本地工作树部署到实时 Hydrolix Kubernetes集群和烟雾测试MCP工具的运行情况豆荚。它被排除在默认测试运行和预推钩之外；跑步它需要通过 end_to_end pytest标记+ 资格证书。看 tests/e2e/README.md 对于runbook。

MCP Hydrolix

快速接入

详细介绍