Hydrolix MCP Server

Name: Hydrolix MCP Server
Author: hydrolix

ローカル

github.com/hydrolixデータベース111 週間前に更新

リポジトリ

Hydrolix MCP Server について

Hydrolix MCP Serverは、MCPクライアントをHydrolixクラスターに接続し、SQLクエリとデータベースメタデータの取得を可能にします。データベースやテーブルの一覧表示、スキーマ確認、クエリ実行のツールを提供します。

主な機能

01SQLのSELECTクエリ実行
02クラスター内データベースの一覧表示
03データベース内テーブルの一覧表示
04テーブルスキーマメタデータの取得
05トークンと認証情報による認証

活用シーン

01Hydrolixクラスター内のデータベース探索
02クエリ前のテーブルスキーマ確認
03目的を記録したSQLクエリの実行
04HTTPまたはSSEでリクエスト単位の認証情報を使用

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

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

ヒント

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

メモ

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

コマンドが見つからない場合

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 上にありません。最も簡単な解決方法はオプション A（uv）に切り替えることです。Python 環境と PATH を自動で管理できます。

Step 4 — Claude Desktop を再起動する

設定を適用するため、アプリを再起動してください。

macOS / Windows のユーザー向け： 再起動する前に、Claude を完全に終了してください。macOS では、Cmd+Q を押すか、Dock アイコンを右クリックして「終了」を選択します。Windows では、システムトレイのアイコンを使用してください。

Step 5 — 動作を確認する

Claude Desktop で新しい会話を開きます。テキスト入力欄の近くにツール／ハンマーのアイコンが表示されていることを確認してください。これは MCP サーバーへの接続が成功したことを示します。
次のプロンプトを試して、すべてが動作していることを確認します。

Hydrolix MCP ツールを使って、利用可能なデータベースを一覧表示してください。

Claude は list_databases ツールを呼び出し、クラスター内のデータベース一覧を返します。

代わりに Claude Code を使う場合

コマンドラインを使う場合は、uv がインストールされていることを確認し（Step 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) を選択し、Step 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 project manager の使用をおすすめします。他のすべての依存関係を分離された環境にインストールできます。

認証

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

リクエストごとの 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 に別途記載されています。

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。