Hydrolix

公式

Hydrolixの時系列データレイク統合により、LLMベースのワークフローにスキーマ探索とクエリ機能を提供します。

GitHub

このMCPを試すスポンサー

Hydrolix MCPで何ができますか？

SQLクエリの実行 — アシスタントに、オプションのセル制限と目的コメントを指定して、Hydrolixクラスターに対してrun_select_queryを実行するよう依頼します。
データベースの一覧表示 — アシスタントにlist_databasesを呼び出させ、Hydrolixクラスターで利用可能なすべてのデータベースを列挙します。
テーブルスキーマの探索 — list_tablesとget_table_infoを使用して、任意のデータベースのテーブルを検出し、スキーマなどのメタデータを取得します。
時間範囲でのクエリ — 特定の日付範囲内でタイムスタンプ順の結果を要求し、プライマリキーの最適化を活用して効率的なクエリを実現します。

ドキュメント

Hydrolix MCP Server

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）を使用した場合は、"args" フィールドなしの "command": "mcp-hydrolix" を使用してください。

[!TIP] ファイルにすでに他のエントリがある場合は、ファイル全体を置き換えるのではなく、既存の "mcpServers" オブジェクト内に "mcp-hydrolix" ブロックを追加してください。

[!NOTE] ユーザー名/パスワードの代わりにサービスアカウントトークンで認証する場合は、Authentication を参照してください。

コマンドが見つかりませんか？

Claude Desktop はシェルの 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 上にありません。最も簡単な修正方法は、Python 環境と PATH を管理するオプション A（uv）に切り替えることです。

ステップ 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: 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 (文字列): テーブルの名前。

効果的な使用方法

LLM アーキテクチャの多様性のため、すべてのモデルが上記のツールを積極的に使用するわけではなく、モデルに提供される慎重に構築されたツールの説明があっても、ガイダンスなしで効果的に使用するモデルはほとんどありません。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 を使用した設定例を以下に示します。

Hydrolix MCP サーバーを起動する推奨方法は、uv プロジェクトマネージャーを介することです。これにより、他のすべての依存関係が分離された環境でインストールされます。

認証

サーバーは複数の認証方法をサポートしており、優先順位は次のとおりです（高い順）:

リクエストごとの 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 トランスポートを使用する場合、少なくとも 1 つの認証方法を設定する必要があります:

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 発行のリクエストにヘッダーを追加できます。これが可能な場合は、セキュリティを高めるために、クエリパラメータではなく Authorization: Bearer <sa-token-here> ヘッダーを介してサービスアカウントトークンを渡すように MCP クライアントを設定することを推奨します。

注: バインドホストとポートの設定は、トランスポートが「http」または「sse」に設定されている場合にのみ使用されます。

オプション変数

エンドポイントのオーバーライド、非推奨の変数エイリアス、およびオプションのチューニング変数の完全なセット（タイムアウト、クエリ SETTINGS のオーバーライド、結果の切り詰め、HTTP/SSE ワーカーのチューニング、プロキシ、メトリクス、エスケープハッチ）については、docs/CONFIG.md を参照してください。

メンテナー

運用特権を必要とするタスク（ライブのHydrolixクラスターに対するエンドツーエンドのスイートの実行、およびリリースの作成）は、MAINTAINERS.mdに別途文書化されています。