Hydrolix

公式

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

GitHub

Hydrolix MCPで何ができますか？

利用可能なデータベースを一覧表示 — アシスタントに、list_databases を使用して Hydrolix クラスター内のすべてのデータベースを列挙するよう依頼します。
データベース内のテーブルを探索 — list_tables を使用して、特定のデータベース内のすべてのテーブルの一覧を要求します。
テーブルスキーマを検査 — get_table_info を使用して、指定されたテーブルの列名、型、メタデータを取得します。
SQLクエリを実行 — run_select_query を使用して Hydrolix クラスターに対して任意のSQLを実行し、ログやイベントデータを分析します。

ドキュメント

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

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

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

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 の上部にある Install in VS Code バッジをクリックすると、ワンクリックでインストールできます。UI フローを使用する場合は、コマンドパレット (Cmd+Shift+P / Ctrl+Shift+P) を開き、MCP: Add Server を実行し、Command (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 に接続できる場合、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 トランスポートモードを使用している場合にのみ利用できます。

注: 読み取り専用ロールを持つサービスアカウントトークンを使用することをお勧めします。

ユーザー名とパスワードを使用した 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 に個別に文書化されています。