Clickzetta MCP サーバー

概要

Clickzetta Lakehouseとのデータベース連携を可能にするモデルコンテキストプロトコル（MCP）サーバー実装。このサーバーは、ツールを用いたSQLクエリの実行や、リソースとして提示されるデータ分析メモとの連携を可能にします。

AIデータエンジニアとしてMCP-ClickZetta-Server/Traeをすぐに使い始める

Traeをダウンロードしてインストールする

AI を使用するには、 trae.ai からダウンロードしてサインインしてください。

ClickZettaアカウントを取得する

MCP-ClickZetta-Server Dockerイメージをプルする

docker pull czqiliang/mcp-clickzetta-server

TraeにMCPサーバーを追加する

AI チャットウィンドウで、[設定] アイコン > [MCP] をクリックします。
MCP ウィンドウが表示されます。
- 追加ボタンをクリックします。
MCP サーバーマーケットプレイスにアクセスします。
「手動設定」をクリックします。「手動設定」ウィンドウが表示されます。以下のJSON設定を入力ボックスに貼り付けて、新しいMCPサーバーを追加し、「確認」ボタンをクリックします。MCPサーバーがMCPリストに追加されます。

{
   "mcpServers": {
      "clickzetta-mcp-server": {
         "command": "docker",
         "args": [
            "run",
            "-i", 
            "--rm", 
            "-e", "LOG_LEVEL=INFO", 
            "-e", "CLICKZETTA_SERVICE", 
            "-e", "CLICKZETTA_INSTANCE",
            "-e", "CLICKZETTA_WORKSPACE",
            "-e", "CLICKZETTA_SCHEMA",
            "-e", "CLICKZETTA_USERNAME",
            "-e", "CLICKZETTA_PASSWORD",
            "-e", "CLICKZETTA_VCLUSTER",
            "-e", "XINFERENCE_BASE_URL",
            "-e", "XINFERENCE_EMBEDDING_MODEL_512",
            "-e", "Similar_table_name",
            "-e", "Similar_embedding_column_name",
            "-e", "Similar_content_column_name",
            "-e", "Similar_partition_scope",
            "czqiliang/mcp-clickzetta-server:latest" 
         ],
         "env": {
            "CLICKZETTA_SERVICE": "api.clickzetta.com", 
            "CLICKZETTA_INSTANCE": "your clickzetta instance", 
            "CLICKZETTA_WORKSPACE": "your clickzetta workspace" ,
            "CLICKZETTA_SCHEMA": "your clickzetta schema",
            "CLICKZETTA_USERNAME": "your clickzetta usename",
            "CLICKZETTA_PASSWORD": "your clickzetta password",
            "CLICKZETTA_VCLUSTER": "your clickzetta vcluster",
            "XINFERENCE_BASE_URL": "http://host.docker.internal:9998",
            "XINFERENCE_EMBEDDING_MODEL_512": "bge-small-zh",
            "Similar_table_name": "clickzegithub_event_issuesevent_embedding.github_event_issuesevent_embedding_512tta_table",
            "Similar_embedding_column_name": "issue_body_embedding",
            "Similar_content_column_name": "issue_body",
            "Similar_partition_scope": "partition_date  >= '2024-01-01' and partition_date  <= '2024-01-15'"
            }
      }
   }
}

CLICKZETTA の env パラメータは必須です
XINFERENCE 値および類似値の env パラメータは選択可能で、vector_search および match_all ツールをサポートします

AIデータエンジニアとしてMCP-ClickZetta-Server/Zettapark-MCP-Server/Claude Desktopを使用したクイックスタート

Claude Desktopをダウンロードしてインストールする

claude.ai からダウンロードしてサインインしてください。

ClickZettaアカウントを取得する

Jupyterラボを始める

Docker Composeから始める

フォルダを作成

mkdir notebooks
cd notebooks

config.json ファイルを作成し、ログイン情報を以下のように設定します。

{
    "username": "your clickzetta lakehouse user name",
    "password": "your clickzetta lakehouse password",
    "service": "api.clickzetta.com",
    "instance": "your clickzetta lakehouse instance name",
    "workspace": "your clickzetta lakehouse workspac name",
    "schema": "your clickzetta lakehouse schema",
    "vcluster": "your clickzetta lakehouse vcluster name",
    "sdk_job_timeout": 60,
    "hints": {
      "sdk.job.timeout": 60,
      "query_tag": "test_zettapark_vector_ns227206",
      "cz.storage.parquet.vector.index.read.memory.cache": "true",
      "cz.storage.parquet.vector.index.read.local.cache": "false",
      "cz.sql.table.scan.push.down.filter": "true",
      "cz.sql.table.scan.enable.ensure.filter": "true",
      "cz.storage.always.prefetch.internal": "true",
      "cz.optimizer.generate.columns.always.valid": "true",
      "cz.sql.index.prewhere.enabled": "true",
      "cz.storage.parquet.enable.io.prefetch": "false"
    }
  }

注意：この方法では、notebooksフォルダ内のconfig.jsonファイルを設定してください。query_tagは目的に応じて変更してください。これはタグでクエリを検索するために使用します。

docker-compose.ymlをダウンロードし、docker composeを起動します。

ここからdocker composeファイルをダウンロードしてください

docker compose up -d

Docker デスクトップに移動し、docker compose が開始されていることを確認します。

Jupyter Lab サーバーにアクセスする

http://localhost:8888/

トークン: YOUR_SECURE_TOKEN

次に、新しいノートブックを作成し、名前を Untitled.ipynb から notebook.ipynb に変更します。

またはローカルサーバーを起動する

# Create a clean environment (Python 3.10 worked during debugging)
conda create -n jupyter_mcp_env python=3.10 -y

# Activate the environment
conda activate jupyter_mcp_env

# Use 'python -m pip' to ensure correct pip in the activated env
python -m pip install jupyterlab ipykernel

# Install the required v2.0.1
python -m pip install "jupyter_collaboration==2.0.1"

# Uninstall potentially conflicting versions
python -m pip uninstall -y pycrdt datalayer_pycrdt

# Install the required version
python -m pip install datalayer_pycrdt

jupyter server extension enable jupyter_collaboration --py --sys-prefix

# Start JupyterLab, please keep token as YOUR_SECURE_TOKEN
jupyter lab --port 8888 --IdentityProvider.token YOUR_SECURE_TOKEN --ip 0.0.0.0

ClaudeデスクトップにMCPサーバーを追加する

Claudeデスクトップで、「設定」→「開発者」→「設定の編集」に移動します。
claude_desktop_config.json を開いて MCP サーバーを設定します

{
   "mcpServers": {

      "jupyter": {
         "command": "docker",
      "args": [
        "run",
        "-i", 
        "--rm", 
        "-e", "SERVER_URL", 
        "-e", "TOKEN",
        "-e", "NOTEBOOK_PATH",
        "-e", "LOG_LEVEL=INFO", 
        "czqiliang/jupyter-mcp-server:latest" 
      ],
      "env": {
        "SERVER_URL": "http://host.docker.internal:8888", 
        "TOKEN": "YOUR_SECURE_TOKEN", 
        "NOTEBOOK_PATH": "notebook.ipynb" 
         }
      },
      "clickzetta-mcp-server": {
         "command": "docker",
         "args": [
            "run",
            "-i", 
            "--rm", 
            "-e", "LOG_LEVEL=INFO", 
            "-e", "CLICKZETTA_SERVICE", 
            "-e", "CLICKZETTA_INSTANCE",
            "-e", "CLICKZETTA_WORKSPACE",
            "-e", "CLICKZETTA_SCHEMA",
            "-e", "CLICKZETTA_USERNAME",
            "-e", "CLICKZETTA_PASSWORD",
            "-e", "CLICKZETTA_VCLUSTER",
            "-e", "XINFERENCE_BASE_URL",
            "-e", "XINFERENCE_EMBEDDING_MODEL_512",
            "-e", "Similar_table_name",
            "-e", "Similar_embedding_column_name",
            "-e", "Similar_content_column_name",
            "-e", "Similar_partition_scope",
            "czqiliang/mcp-clickzetta-server:latest" 
         ],
         "env": {
            "CLICKZETTA_SERVICE": "api.clickzetta.com", 
            "CLICKZETTA_INSTANCE": "your clickzetta instance", 
            "CLICKZETTA_WORKSPACE": "your clickzetta workspace" ,
            "CLICKZETTA_SCHEMA": "your clickzetta schema",
            "CLICKZETTA_USERNAME": "your clickzetta usename",
            "CLICKZETTA_PASSWORD": "your clickzetta password",
            "CLICKZETTA_VCLUSTER": "your clickzetta vcluster",
            "XINFERENCE_BASE_URL": "http://host.docker.internal:9998",
            "XINFERENCE_EMBEDDING_MODEL_512": "bge-small-zh",
            "Similar_table_name": "clickzegithub_event_issuesevent_embedding.github_event_issuesevent_embedding_512tta_table",
            "Similar_embedding_column_name": "issue_body_embedding",
            "Similar_content_column_name": "issue_body",
            "Similar_partition_scope": "partition_date  >= '2024-01-01' and partition_date  <= '2024-01-15'"
            }
      }
   }
}

Zettapark MCP サーバーに関する詳細情報はここから入手できます。

コンポーネント

リソース

サーバーは単一の動的リソースを公開します:

memo://insights : 分析中に発見された洞察を集約した、継続的に更新されるデータ洞察メモ
- 追加インサイトツールで新しいインサイトが発見されると自動更新されます

ツール

サーバーは次のコアツールを提供します。

クエリツール

`read_query`

説明: SELECTクエリを実行してデータベースからデータを読み取ります。
入力:
- query (文字列): 実行するSELECT SQL クエリ。
戻り値: クエリ結果をオブジェクトの配列として返します。

`write_query` ( `--allow-write`フラグが必要)

説明: INSERT 、 UPDATE 、またはDELETEクエリを実行してデータを変更します。
入力:
- query (文字列): SQL 変更クエリ。
戻り値: { affected_rows: number } (影響を受けた行の数を示します)。

`create_table` ( `--allow-write`フラグが必要)

説明: データベースに新しいテーブルを作成します。
入力:
- query (文字列): CREATE TABLE SQL ステートメント。
戻り値: テーブル作成の確認。

`create_table_with_prompt` ( `--allow-write`フラグが必要)

説明: ユーザーにテーブル名、列、およびそのタイプを入力するよう求めて、新しいテーブルを作成します。
入力:
- table_name (文字列): 作成するテーブルの名前。
- columns (文字列): column1:type1,column2:type2形式の列とそのタイプ。
戻り値: テーブル作成の確認。

スキーマツール

`list_tables`

説明: データベース内のすべてのテーブルのリストを取得します。
入力: 入力は不要です。
戻り値: テーブル名の配列。

`describe_table`

説明: 特定のテーブルの列情報を表示します。
入力:
- table_name (文字列): 説明するテーブルの名前 (完全修飾名でも可)。
戻り値: 名前とタイプを含む列定義の配列。

`show_object_list`

説明: カタログ、スキーマ、テーブルなど、現在のワークスペース内の特定のオブジェクトタイプのリストを取得します。
入力:
- object_type (文字列): 表示するオブジェクトのタイプ。
戻り値: オブジェクトのリスト。

`desc_object`

説明: カタログ、スキーマ、テーブルなどの特定のオブジェクトに関する詳細情報を取得します。
入力:
- object_type (文字列): オブジェクトのタイプ。
- object_name (文字列): オブジェクトの名前。
戻り値: オブジェクトに関する詳細情報。

分析ツール

`append_insight`

説明: メモリソースに新しいデータインサイトを追加します。
入力:
- insight (文字列): 分析から発見されたデータの洞察。
戻り値: インサイト追加の確認。
トリガー: memo://insightsリソースを更新します。

データインポートツール

`import_data_into_table_from_url`

説明: URL（ファイルパスまたはHTTP/HTTPS URLを含む）からテーブルにデータをインポートします。インポート先のテーブルが存在しない場合は、自動的に作成されます。
入力:
- from_url (文字列): データソースの URL。
- dest_table (文字列): データをインポートするテーブル。
戻り値: データのインポートが成功したことの確認。

`import_data_into_table_from_database`

説明：データベースに接続し、クエリを実行し、結果をClickzettaテーブルにインポートします。MySQL、PostgreSQL、SQLite、その他の一般的なデータベースタイプをサポートしています。
入力:
- db_type (文字列): データベースの種類 (例: mysql 、 postgresql 、 sqlite )。
- host (文字列): データベースサーバーのホスト名または IP アドレス (SQLite では必要ありません)。
- port (整数): データベースサーバーのポート番号 (SQLite では必要ありません)。
- database (文字列): 接続するデータベースの名前 (SQLite の場合、これはデータベースファイルへのファイルパスです)。
- username (文字列): 認証用のユーザー名 (SQLite では必要ありません)。
- password (文字列): 認証用のパスワード (SQLite では必要ありません)。
- source_table (文字列): ソーステーブル名。
- dest_table (文字列): 宛先テーブル名。
戻り値: データのインポートが成功したことの確認。

類似検索ツール

`vector_search`

説明: 質問を使用してテーブルでベクトル検索を実行し、最も近い上位 5 つの回答を返します。
入力:
- table_name (文字列): テーブル名。
- content_column_name (文字列): コンテンツを格納する列。
- embedding_column_name (文字列): 埋め込みを格納する列。
- partition_scope (文字列): WHERE条件の一部としてパーティションスコープを定義する SQL コード。
- question (文字列): 検索する質問。
返されるもの: 検索結果。

`match_all`

説明: 質問のあるテーブルで「すべて一致」機能を使用して検索を実行し、上位 5 つの回答を返します。
入力:
- table_name (文字列): テーブル名。
- content_column_name (文字列): コンテンツを格納する列。
- partition_scope (文字列): WHERE条件の一部としてパーティションスコープを定義する SQL コード。
- question (文字列): 検索する質問。
返されるもの: 検索結果。

知識検索ツール

`get_knowledge_about_how_to_do_something`

説明: 遅いクエリの分析、テーブルの作成、ストレージ接続の管理など、特定のタスクを実行する方法に関するガイダンスを提供します。
入力:
- to_do_something (文字列): 実行するタスク。サポートされているタスクは次のとおりです。
  - analyze_slow_query
  - analyze_table_with_small_file
  - create_table_syntax
  - how_to_create_vcluster
  - how_to_create_index
  - how_to_alter_table_and_column
  - how_to_create_storage_connection
  - how_to_create_external_volume
戻り値: 指定されたタスクに関する詳細なガイダンス。

使用上の注意

データを変更するツール ( write_query 、 create_tableなど) を使用する場合は--allow-writeフラグが有効になっていることを確認してください。
上記のように、各ツールに正しい入力パラメータを指定します。

Claude Desktopでの使用

ローカル MCP サーバーとしてインストールする (この方法は MacOS でテストおよび検証済みです)

このリポジトリをクローンします:

git clone https://github.com/yunqiqiliang/mcp-clickzetta-server.git
cd mcp-clickzetta-server

パッケージをインストールします。

uv pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple/

設定資格情報

Clickzetta Lakehouse の資格情報を使用して、.env.example に基づいて .env ファイルを作成します。

CLICKZETTA_USERNAME = ""
CLICKZETTA_PASSWORD = ""
CLICKZETTA_SERVICE = "api.clickzetta.com"
CLICKZETTA_INSTANCE = ""
CLICKZETTA_WORKSPACE = ""
CLICKZETTA_SCHEMA = ""
CLICKZETTA_VCLUSTER = ""
XINFERENCE_BASE_URL = "http://********:9998"
XINFERENCE_EMBEDDING_MODEL_512 = "bge-small-zh"
Similar_table_name = "github_event_issuesevent_embedding.github_event_issuesevent_embedding_512"
Similar_embedding_column_name = "issue_body_embedding"
Similar_content_column_name = "issue_body"
Similar_partition_scope = "partition_date  >= '2024-01-01' and partition_date  <= '2024-01-15'"

使用法

UVで走る

パッケージをインストールした後、次のコマンドでサーバーを直接実行できます。

uv run mcp_clickzetta_server

サーバーを初めて実行する場合は、次のコマンドを実行してパッケージのインストールを高速化できます。

UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/ uv run mcp_clickzetta_server

これにより、stdio ベースの MCP サーバーが起動し、Claude Desktop または stdio 通信をサポートする任意の MCP クライアントに接続できるようになります。

次のような出力が表示されます。

uv run mcp_clickzetta_server --no-prefetch

2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Starting Clickzetta MCP Server
2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Allow write operations: False
2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Prefetch table descriptions: True
2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Excluded tools: []
2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Prefetching table descriptions
2025-03-25 10:11:21,726 - clickzetta.zettapark.session - INFO - Zettapark Session information: 
"version" : 0.1.3,
"python.version" : 3.12.2,
"python.connector.version" : 0.8.89.0,
"python.connector.session.id" : dd46bd27-920d-4760-94a6-6f994d31e63e,
"os.name" : Darwin

2025-03-25 10:11:21,728 - clickzetta.connector.v0.client - INFO - clickzetta connector submitting job,  id:2025032510112172821098301
2025-03-25 10:11:23,059 - clickzetta.connector.v0.client - INFO - clickzetta connector submitting job,  id:2025032510112305897947697
2025-03-25 10:11:23,728 - mcp_clickzetta_server - INFO - Allowed tools: ['read_query', 'append_insight']
2025-03-25 10:11:23,732 - mcp_clickzetta_server - INFO - Server running with stdio transport

クロードデスクトップ統合

コマンド:docker

MCP サーバー（Docker で実行）は、MCP クライアント構成（例： claude_desktop_config.json ）を介して渡された環境変数から構成を読み取ります。主な変数：

{
   "clickzetta-mcp-server": {
         "command": "docker",
         "args": [
            "run",
            "-i", 
            "--rm", 
            "-e", "LOG_LEVEL=INFO", 
            "-e", "CLICKZETTA_SERVICE", 
            "-e", "CLICKZETTA_INSTANCE",
            "-e", "CLICKZETTA_WORKSPACE",
            "-e", "CLICKZETTA_SCHEMA",
            "-e", "CLICKZETTA_USERNAME",
            "-e", "CLICKZETTA_PASSWORD",
            "-e", "CLICKZETTA_VCLUSTER",
            "-e", "XINFERENCE_BASE_URL",
            "-e", "XINFERENCE_EMBEDDING_MODEL_512",
            "-e", "Similar_table_name",
            "-e", "Similar_embedding_column_name",
            "-e", "Similar_content_column_name",
            "-e", "Similar_partition_scope",
            "czqiliang/mcp-clickzetta-server:latest" 
         ],
         "env": {
            "CLICKZETTA_SERVICE": "api.clickzetta.com", 
            "CLICKZETTA_INSTANCE": "your clickzetta instance", 
            "CLICKZETTA_WORKSPACE": "your clickzetta workspace" ,
            "CLICKZETTA_SCHEMA": "your clickzetta schema",
            "CLICKZETTA_USERNAME": "your clickzetta usename",
            "CLICKZETTA_PASSWORD": "your clickzetta password",
            "CLICKZETTA_VCLUSTER": "your clickzetta vcluster",
            "XINFERENCE_BASE_URL": "http://host.docker.internal:9998",
            "XINFERENCE_EMBEDDING_MODEL_512": "bge-small-zh",
            "Similar_table_name": "clickzegithub_event_issuesevent_embedding.github_event_issuesevent_embedding_512tta_table",
            "Similar_embedding_column_name": "issue_body_embedding",
            "Similar_content_column_name": "issue_body",
            "Similar_partition_scope": "partition_date  >= '2024-01-01' and partition_date  <= '2024-01-15'"
            }
      }
}

コマンド:uv

Claudeデスクトップで、「設定」→「MCPサーバー」に移動します。
uv 実行可能ファイルへのフルパスを使用して新しいサーバーを追加します。

{
   "mcpServers": {
      "clickzetta-mcp-server" : {
         "command": "/Users/******/anaconda3/bin/uv",
         "args": [
            "--directory",
            "/Users/******/Documents/GitHub/mcp-clickzetta-server",
            "run",
            "mcp_clickzetta_server"
         ]
      }
   }
}

ターミナルでwhich uvを実行するとUVパスが見つかります。
サーバー設定を保存する

クエリの例

Claude を使用する場合は、次のような質問をすることができます。

「Clickzetta アカウント内のすべてのスキーマを一覧表示できますか？」
「PUBLICスキーマ内のすべてのビューを一覧表示する」
「SALESスキーマのCUSTOMER_ANALYTICSビューの構造について説明します」
「FINANCEスキーマのREVENUE_BY_REGIONビューのサンプルデータを表示してください」
「次のSQLクエリを実行します: SELECT customer_id, SUM(order_total) as total_spend FROM SALES.ORDERS GROUP BY customer_id ORDER BY total_spend DESC LIMIT 10」
「マーケティングデータベースを照会して、コンバージョン率で上位5つのキャンペーンを見つけます」
「私たちは Clickzetta からデータを取得し、公開されているこのスキーマの github_users テーブルで各企業のユーザー数を分析しました。結果を中国語で返し、その結果に対してデータの閲覧を実行します。」
"帮我从Clickzetta中读取データデータ、分析下公開このスキーマの下にあるgithub_event_issuesevent表里にどのような条记录がありますか?"

例の結果

「私たちは Clickzetta データソースからデータを取得し、github_users テーブルの公開スキーマに基づいて先の分析を行っています。これらの分析は可能ですか? 、レポート、およびさまざまな典拠のユーザー分析モデルには、ユーザー値分析、ユーザーのライフサイクル分析、ユーザーセグメントなどが含まれ、これらの分析内容に基づいて分析レポートのダッシュボードが生成されます。

「Clickzetta からデータを取得し、公開されているこのスキーマの github_users テーブルで各企業のユーザー数を分析しました。結果を中国語で返し、その結果に対してデータ公開を実行しました」の結果:

「Clickzetta からデータを取得し、パブリックなこのスキーマの下にある github_users テーブルの各場所のユーザー数を分析しました。結果を中国語で返し、その結果に対してデータ公開を実行しました」の結果:

セキュリティに関する考慮事項

このサーバー:

読み取り専用操作を強制します（SELECT ステートメントのみが許可されます）
結果セットが大きくなるのを防ぐために、LIMIT句を自動的に追加します。
安全な接続のためにサービスアカウント認証を使用します
SQLインジェクションを防ぐために入力を検証します
⚠️ 重要: .env ファイルは安全な場所に保管し、バージョン管理にコミットしないでください。.gitignore ファイルは除外するように設定されています。

Smithery経由でのインストール（この方法はテストおよび検証が必要です）

Smithery経由で Claude Desktop 用の Clickzetta Server を自動的にインストールするには:

npx -y @smithery/cli@latest install @yunqiqiliang/mcp-clickzetta-server --client claude --key ******

UVX経由でインストールする（この方法はテストおよび検証が必要です）

# Add the server to your claude_desktop_config.json
"mcpServers": {
  "clickzetta_pip": {
      "command": "uvx",
      "args": [
          "mcp_clickzetta_server",
          "--service",
          "the_service",
          "--instance",
          "the_instance",
          "--vcluster",
          "the_vcluster",
          "--workspace",
          "the_workspace",
           "--schema",
          "the_schema",
          "--user",
          "the_user",
          "--password",
          "their_password",
          # Optionally: "--allow_write" (but not recommended)
          # Optionally: "--log_dir", "/absolute/path/to/logs"
          # Optionally: "--log_level", "DEBUG"/"INFO"/"WARNING"/"ERROR"/"CRITICAL"
          # Optionally: "--exclude_tools", "{tool name}", ["{other tool name}"]
      ]
  }
}

Integrations