Hydrolix MCP Server

公式

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

GitHub

ドキュメント

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 だけでは不十分です。

エンドポイントの上書き

これらは HYDROLIX_URL から派生した値を上書きします。HTTP クエリエンドポイントとバージョン API が異なる内部ホスト名またはポートで動作するクラスター内デプロイメントに役立ちます。上書きの優先順位: 明示的な新しい変数 > 非推奨のエイリアス > HYDROLIX_URL 派生 > ハードデフォルト。

HYDROLIX_HTTP_QUERY_HOST / HYDROLIX_HTTP_QUERY_PORT / HYDROLIX_HTTP_QUERY_SECURE: ClickHouse HTTP クエリエンドポイントを上書きします。
HYDROLIX_VERSION_API_HOST / HYDROLIX_VERSION_API_PORT / HYDROLIX_VERSION_API_SECURE: REST /version プローブエンドポイントを上書きします。HYDROLIX_VERSION_API_SECURE は、デフォルトで解決された HTTP クエリの secure 値から継承します。

非推奨の変数

以下は移行期間中も引き続き使用できますが、将来のリリースで削除されます。都合の良いときに移行してください。

非推奨	代替
`HYDROLIX_HOST`	`HYDROLIX_URL` (推奨) または `HYDROLIX_HTTP_QUERY_HOST`
`HYDROLIX_PORT`	`HYDROLIX_HTTP_QUERY_PORT`
`HYDROLIX_SECURE`	`HYDROLIX_HTTP_QUERY_SECURE`
`HYDROLIX_API_HOST`	`HYDROLIX_VERSION_API_HOST`
`HYDROLIX_API_PORT`	`HYDROLIX_VERSION_API_PORT`

これらを使用している外部オペレーターには、HYDROLIX_URL への移行を促す一度限りの起動警告が表示されます。クラスター内 (o6r 管理) デプロイメントではこの警告は表示されず、移行はプラットフォームによって処理されます。

認証変数

stdio トランスポートを使用する場合、少なくとも 1 つの認証方法を設定する必要があります。

HYDROLIX_TOKEN: 環境ベースの認証用のサービスアカウントトークン
HYDROLIX_USER と HYDROLIX_PASSWORD: 環境ベースの認証用のユーザー名とパスワード (両方を一緒に提供する必要があります)

まとめ:

stdio の場合、HYDROLIX_TOKEN または HYDROLIX_USER+HYDROLIX_PASS (環境認証情報) を使用する必要があります。
http/sse の場合、HYDROLIX_TOKEN または HYDROLIX_USER+HYDROLIX_PASS (環境認証情報) を使用できますが、代わりにリクエストごとの認証情報を使用することもできます。

環境またはリクエストを通じて認証情報が提供されない場合、リクエストは失敗します。

オプション変数

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 InspectorまたはHTTPトランスポートを使用したリモートアクセスの場合:

HYDROLIX_URL=https://my-cluster.hydrolix.net
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サーバーをローカルで実行することをサポートしていないクライアントに役立ちます。

リクエストごとの認証を使用してリモート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"に設定されている場合にのみ使用されます。

エンドツーエンドテスト

tests/e2e/ の下にある別のスイートは、ローカルのワーキングツリーを稼働中の Hydrolix Kubernetesクラスターにデプロイし、実行中のポッドに対してMCPツールのスモークテストを実施します。これはデフォルトのテスト実行とpre-pushフックからは除外されており、実行には end_to_end pytestマーカーによる明示的なオプトインと認証情報が必要です。ランブックについてはtests/e2e/README.mdを参照してください。