Skip to main content
Glama
mcp-clickhousex

mcp-clickhousex

MCP ClickHouse Tool

CI PyPI Python 3.13+ License: MIT

ClickHouse 用の読み取り専用の Model Context Protocol (MCP) サーバーです。メタデータの検出、リソース、パラメータ化された SELECT クエリ、SHOW イントロスペクション、クエリ分析、大規模な結果セット向けのスナップショットモードをサポートし、プロファイルベースの設定と厳格な DML/DDL 禁止を備えています。

要件: Python 3.13+、実行中の ClickHouse インスタンス、および環境変数または設定ファイルによる接続情報。

クイックスタート

DSN を設定し、MCP Inspector でサーバーを実行します:

# Option 1: Run directly with uvx (no clone needed)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector uvx mcp-clickhousex
# Option 2: Run from source (clone repo, then)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector uv run main.py

Related MCP server: io.github.Aguantar/clickhouse-dataops-mcp

設定

すべての設定は MCP_CLICKHOUSE プレフィックスを使用します。フラットな環境変数(例: MCP_CLICKHOUSE_DSN)は、単一の接続を持つ場合に デフォルト プロファイルを設定するための簡単な方法です。複数のプロファイルの場合は、ユーザースコープの config.json ファイルが推奨されます。

単一接続: 環境変数で設定します。

# Connection DSN (required).
export MCP_CLICKHOUSE_DSN="http://user:password@host:8123/database"

# Optional description for the default profile (tooling/AI discovery).
export MCP_CLICKHOUSE_DESCRIPTION="Primary cluster"

# Optional max rows per interactive query (default 500; hard ceiling 1000).
export MCP_CLICKHOUSE_QUERY_MAX_ROWS="500"

# Optional interactive query timeout in seconds (default 30; hard ceiling 300).
export MCP_CLICKHOUSE_QUERY_COMMAND_TIMEOUT_SECONDS="30"

# Optional max rows for snapshot queries (default 10000; hard ceiling 50000).
export MCP_CLICKHOUSE_SNAPSHOT_MAX_ROWS="10000"

# Optional snapshot query timeout in seconds (default 120; hard ceiling 300).
export MCP_CLICKHOUSE_SNAPSHOT_COMMAND_TIMEOUT_SECONDS="120"

複数接続: ユーザースコープの config.json ファイルを使用します(推奨)。環境変数は MCP_CLICKHOUSE_PROFILES_<NAME>_ プレフィックス(例: MCP_CLICKHOUSE_PROFILES_WAREHOUSE_DSN)でも機能します。

  • Unix 系: ~/.config/mcp-clickhousex/config.json

  • Windows: %USERPROFILE%\.config\mcp-clickhousex\config.json

例(config.json):

{
  "profiles": {
    "default": {
      "dsn": "http://default:@localhost:8123/default",
      "description": "Primary",
      "query_max_rows": 500,
      "query_command_timeout_seconds": 60,
      "snapshot_max_rows": 10000,
      "snapshot_command_timeout_seconds": 120
    },
    "warehouse": {
      "dsn": "http://user:pass@warehouse:8123/analytics",
      "description": "Warehouse"
    }
  }
}

認証情報の特殊文字: ユーザー名またはパスワードに URL 予約文字が含まれる場合は、DSN 内でパーセントエンコードしてください:

文字

エンコーディング

#

%23

?

%3F

/

%2F

@

%40

%

%25

たとえば、ユーザー名 admin@org とパスワード p#ss? は、DSN 内で admin%40org:p%23ss%3F になります: http://admin%40org:p%23ss%3F@host:8123/database

ツール

ツールの説明は server.py のツール docstring と一致しますが、[ClickHouse] プレフィックスはここでは省略されています(MCP で公開されるメタデータには残ります)。パラメータのテキストは、同じツールの各 Field(description=…) と一致します。

Tool

Description

Key params

list_profiles

設定済みプロファイルを一覧表示します。各エントリには名前と任意の説明が含まれます。

—

get_cluster_properties

クラスタのプロパティと実行制限を取得します。ClickHouseサーバーバージョンと、プロファイルに適用される制限(最大行数、タイムアウト)を返します。

profile — プロファイル名。省略時はデフォルトプロファイルを使用。Src: profiles。

run_query

読み取り専用のSELECTまたはWITH … SELECTを実行します。1ステートメントのみ。DML、DDL、SET、SYSTEMなどは拒否されます。{data, row_count}を返します。dataはRFC 4180 CSV文字列です。snapshot=trueを渡すと結果をディスクに保存し、代わりに{snapshot_uri, row_count}を受け取ります。CSVはスナップショットリソースURI経由で取得します。最大行数制限あり。超過時はtruncatedとrow_limitが設定されます。SQL検証はanalyze_queryと同じです。

sql(必須)— 読み取り専用のSELECTまたはWITH … SELECT。1ステートメントのみ。修飾されたdb.tableまたはdatabaseを使用。パラメータのドライバプレースホルダ構文。parameters — ドライバプレースホルダの名前付きパラメータ(例:%(name)sまたは{name:Type})。database — 非修飾名のセッション既定データベース。Src: databases。profile — プロファイル名。省略時はデフォルトプロファイルを使用。Src: profiles。snapshot — trueの場合、完全な結果をCSVファイルとして保存し、インラインデータの代わりにリソースURI(chx://snapshots/{id})を返します。対話型の行数制限(1 000)を超える可能性のあるクエリに使用します。スナップショット制限が適用されます(既定10 000行、上限50 000行)。エントリは7日後に失効します。

run_show

SHOWイントロスペクションステートメントを実行します。呼び出しごとに1ステートメント。INTO OUTFILEは拒否されます。対話型の行数制限が適用されます(既定500、上限1 000)。タイムアウトはrun_queryと同じです。

sql(必須)— 単一のSHOWステートメント(例:SHOW DATABASES、SHOW CREATE TABLE)。INTO OUTFILEは不可。parameters — ドライバプレースホルダの名前付きパラメータ(例:%(name)sまたは{name:Type})。database — 非修飾名のセッション既定データベース。Src: databases。profile — プロファイル名。省略時はデフォルトプロファイルを使用。Src: profiles。

analyze_query

読み取り専用のSELECTまたはWITH … SELECTをEXPLAINします。プラン、パイプライン、構文テキストを返します。既定のタイプはプランとパイプラインです。クエリタイムアウトと任意のデータベースを使用します。run_queryとは異なり最大行数制限はありません。

sql(必須)— EXPLAIN用の読み取り専用SELECTまたはWITH … SELECT。1ステートメントのみ。run_queryと同じ検証。parameters — ドライバプレースホルダの名前付きパラメータ(例:%(name)sまたは{name:Type})。database — 非修飾名のセッション既定データベース。Src: databases。profile — プロファイル名。省略時はデフォルトプロファイルを使用。Src: profiles。types — EXPLAINのバリアント:plan(インデックス)、pipeline、syntax。省略時は既定でplanとpipeline。

list_databases

データベースを一覧表示します。接続から見えるsystem.databasesの行。

profile — プロファイル名。省略時はデフォルトプロファイルを使用。Src: profiles。

list_tables

データベース内のテーブルとビューを一覧表示します。system.tablesの行:クエリ計画用のname、engine、primary_key、sorting_key、partition_key、total_rows、total_bytes。

database — 一覧表示するデータベース。省略時はクライアント既定。Src: databases。profile — プロファイル名。省略時はデフォルトプロファイルを使用。Src: profiles。

list_columns

テーブルまたはビューの列を一覧表示します。解決されたデータベースとテーブルのsystem.columnsの行。

table(必須)— テーブル名またはビュー名、あるいはdatabase.table。Src: tables。database — tableが非修飾の場合のデータベース。tableにドットが含まれる場合は無視されます。省略時はクライアント既定。Src: databases。profile — プロファイル名。省略時はデフォルトプロファイルを使用。Src: profiles。

リソース

サーバーは、上記のツールと同じディスカバリとメタデータを、URI アドレス可能なリソース(プロファイル優先の階層)として公開します。各リソースの description は対応するツール(list_profiles、get_cluster_properties、list_databases、list_tables、list_columns)と一致し、さらに URI パスパラメータ用の Src: タグが付きます。すべてのリソースコンテンツは JSON(application/json)ですが、スナップショットのみ CSV(text/csv)を返します。デフォルトのプロファイルまたはデータベースにはパスセグメント default を使用します。

リソースの説明は server.py の @mcp.resource の description=… と一致します(上記と同じプレフィックス省略)。

URI

説明

chx://profiles

設定済みプロファイルの一覧。各エントリには名前と任意の説明が含まれます。

chx://profiles/{profile}/cluster-properties

クラスタのプロパティと実行制限を取得します。プロファイルの ClickHouse サーバーバージョンと適用される制限(最大行数、タイムアウト)を返します。Src: profiles。

chx://profiles/{profile}/databases

データベースの一覧。接続に表示される system.databases の行。Src: profiles。

chx://profiles/{profile}/databases/{database}/tables

データベース内のテーブルとビューの一覧。system.tables の行: クエリプランニング用の name、engine、primary_key、sorting_key、partition_key、total_rows、total_bytes。Src: profiles, dbs。

chx://profiles/{profile}/databases/{database}/tables/{table}/columns

テーブルまたはビューの列の一覧。解決されたデータベースとテーブルの system.columns の行。Src: profiles, dbs, tables。

chx://snapshots/{id}

ID によるクエリ結果スナップショットの取得。完全な結果を CSV 文字列(ヘッダー行 + データ行)として返します。エントリは 7 日後に期限切れになります。Src: run_query with snapshot=true。

セキュリティ

読み取り専用 SQL のみ: run_query は SELECT / WITH … SELECT を許可し、run_show は呼び出しごとに単一の SHOW ステートメントを許可します。INTO OUTFILE は run_show では許可されません。対話型クエリは厳格な行数上限(デフォルト 500、ハード上限 1,000)を適用します。より大きな抽出には snapshot=true(デフォルト 10,000、ハード上限 50,000)を使用します。パラメータ化クエリは、ドライバーが許可する場合にサポートされます(%(name)s または {name:Type} 構文)。接続資格情報には環境変数を使用してください。シークレットをコミットしないでください。

MCP ホストの例

uvx mcp-clickhousex を使用した一般的な MCP クライアントのスニペット(クローンは不要。uv が PATH にあることを確認してください)。必要に応じて接続情報を置き換えてください。

Cursor

{
  "mcpServers": {
    "clickhouse": {
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

Codex

[mcp_servers.clickhouse]
command = "uvx"
args = ["mcp-clickhousex"]

[mcp_servers.clickhouse.env]
MCP_CLICKHOUSE_DSN = "http://default:@localhost:8123/default"

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clickhouse": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "mcp-clickhousex"],
      "environment": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "clickhouse": {
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

Copilot

{
  "inputs": [],
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

設定ファイルの場所: Cursor .cursor/mcp.json、Codex/Copilot/OpenCode はクライアントによって異なります。クライアントの MCP ドキュメントを参照してください。

テスト

テストには実行中の ClickHouse インスタンスが必要です。テストスイートはデフォルトデータベースにサンプルテーブルを作成し、データを投入して、最後に削除します。

# Run all tests (unit + functional + e2e)
uv run pytest tests/ -v

テストハーネスは MCP_TEST_CLICKHOUSE_DSN を使用して ClickHouse インスタンスを特定します。未設定の場合は http://admin:password123@localhost:8123/default にフォールバックします。この変数を設定すると、本番の MCP_CLICKHOUSE_DSN に影響を与えずに、テストを別のサーバーに向けることができます:

export MCP_TEST_CLICKHOUSE_DSN="http://user:pass@testhost:8123/default"
uv run pytest tests/ -v

ロードマップ

現時点で計画されている機能はありません。改善の提案は issue を開いてください。

コントリビューション

issue または PR を開いてください。既存のスタイルに従い、適切な場所にテストを追加してください。

ライセンス

MIT。 LICENSE を参照してください。

Available Tools

8 tools
analyze_queryA
Read-only

[ClickHouse] Explain read-only SELECT or WITH … SELECT.

Returns plan, pipeline, and/or syntax text. Default types plan and pipeline. Uses query timeout and optional database; no max-rows cap unlike run_query.

Inputs: sql (required), types, profile, database, +1 more. Returns: Structured EXPLAIN text output keyed by explain type.

get_cluster_propertiesA
Read-only

[ClickHouse] Get cluster properties and execution limits.

Returns ClickHouse server version plus enforced limits (max rows, timeouts) for the profile.

Inputs: profile. Returns: ClickHouse cluster metadata safe to surface to MCP clients.

list_columnsA
Read-only

[ClickHouse] List columns for a table or view.

Rows from system.columns for the resolved database and table.

Inputs: table (required), profile, database. Returns: Generic tabular result with ordered columns and aligned row values.

list_databasesB
Read-only

[ClickHouse] List databases.

Rows from system.databases visible to the connection.

Inputs: profile. Returns: Generic tabular result with ordered columns and aligned row values.

list_profilesA
Read-only

[ClickHouse] List configured profiles.

Each entry includes name and optional description.

Inputs: no named parameters. Returns: result

list_tablesA
Read-only

[ClickHouse] List tables and views in a database.

Rows from system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes for query planning.

Inputs: profile, database. Returns: Generic tabular result with ordered columns and aligned row values.

run_queryA
Read-only

[ClickHouse] Execute read-only SELECT or WITH … SELECT.

One statement; DML, DDL, SET, SYSTEM, and similar are rejected. Max-rows cap; overflow sets truncated and row_limit. Same SQL validation as analyze_query.

Returns {data, row_count} where data is an RFC 4180 CSV string. Pass snapshot=true to persist the result to disk and receive a {snapshot_uri, row_count} instead; fetch the CSV via the snapshot resource URI.

Inputs: sql (required), profile, database, snapshot, +1 more. Returns: result

run_showA
Read-only

[ClickHouse] Execute SHOW introspection statement.

One statement per call; INTO OUTFILE rejected. Interactive row limits apply (default 500, hard ceiling 1 000). Same timeout as run_query.

Inputs: sql (required), profile, database, parameters. Returns: Result of a SHOW introspection statement (columns + rows + optional truncation).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a distinct purpose: listing profiles, cluster properties, running SELECT queries, running SHOW statements, analyzing queries, and listing databases, tables, and columns. No overlap in functionality.

    Naming Consistency4/5

    Uses snake_case consistently, but mixes verb prefixes: 'list_', 'get_', 'run_', 'analyze_'. The pattern is somewhat predictable within categories (metadata listing uses 'list_', execution uses 'run_'), but not fully uniform.

    Tool Count5/5

    8 tools is well-scoped for a read-only ClickHouse client. Covers metadata discovery, query execution, and analysis without unnecessary tools.

    Completeness4/5

    Covers essential read-only operations: metadata listing, SELECT, SHOW, and EXPLAIN. Lacks DDL/DML support, but that is intentional. Minor gap: no tool to retrieve table DDL or status.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server for ClickHouse with enhanced filtering for database and table discovery, supporting LIKE/NOT LIKE patterns and both ClickHouse and chDB tools.
      3
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      A DataOps-focused MCP server for ClickHouse that provides query optimization advice, pipeline latency analysis, and data quality monitoring, with read-only safety.
      8
      32 PyPI
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server for exploratory data analysis across PostgreSQL, MySQL, and ClickHouse databases, providing safe, read-only access with comprehensive analysis capabilities.
      10
      84 PyPI
      6
      MIT