mcp-clickhousex
MCP ClickHouse Tool
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.pyRelated 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.jsonWindows:
%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 内でパーセントエンコードしてください:
文字 | エンコーディング |
|
|
|
|
|
|
|
|
|
|
たとえば、ユーザー名 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 |
| 設定済みプロファイルを一覧表示します。各エントリには名前と任意の説明が含まれます。 | — |
| クラスタのプロパティと実行制限を取得します。ClickHouseサーバーバージョンと、プロファイルに適用される制限(最大行数、タイムアウト)を返します。 |
|
| 読み取り専用のSELECTまたはWITH … SELECTを実行します。1ステートメントのみ。DML、DDL、SET、SYSTEMなどは拒否されます。 |
|
| SHOWイントロスペクションステートメントを実行します。呼び出しごとに1ステートメント。INTO OUTFILEは拒否されます。対話型の行数制限が適用されます(既定500、上限1 000)。タイムアウトはrun_queryと同じです。 |
|
| 読み取り専用のSELECTまたはWITH … SELECTをEXPLAINします。プラン、パイプライン、構文テキストを返します。既定のタイプはプランとパイプラインです。クエリタイムアウトと任意のデータベースを使用します。run_queryとは異なり最大行数制限はありません。 |
|
| データベースを一覧表示します。接続から見えるsystem.databasesの行。 |
|
| データベース内のテーブルとビューを一覧表示します。system.tablesの行:クエリ計画用のname、engine、primary_key、sorting_key、partition_key、total_rows、total_bytes。 |
|
| テーブルまたはビューの列を一覧表示します。解決されたデータベースとテーブルのsystem.columnsの行。 |
|
リソース
サーバーは、上記のツールと同じディスカバリとメタデータを、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 | 説明 |
| 設定済みプロファイルの一覧。各エントリには名前と任意の説明が含まれます。 |
| クラスタのプロパティと実行制限を取得します。プロファイルの ClickHouse サーバーバージョンと適用される制限(最大行数、タイムアウト)を返します。Src: profiles。 |
| データベースの一覧。接続に表示される system.databases の行。Src: profiles。 |
| データベース内のテーブルとビューの一覧。system.tables の行: クエリプランニング用の name、engine、primary_key、sorting_key、partition_key、total_rows、total_bytes。Src: profiles, dbs。 |
| テーブルまたはビューの列の一覧。解決されたデータベースとテーブルの system.columns の行。Src: profiles, dbs, tables。 |
| 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 toolsanalyze_queryARead-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_propertiesARead-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_columnsARead-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_databasesBRead-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_profilesARead-only
[ClickHouse] List configured profiles.
Each entry includes name and optional description.
Inputs: no named parameters. Returns: result
list_tablesARead-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_queryARead-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_showARead-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
Scored across 8 tools
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.
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.
8 tools is well-scoped for a read-only ClickHouse client. Covers metadata discovery, query execution, and analysis without unnecessary tools.
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
Related MCP Connectors
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Hosted BigQuery MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server for ClickHouse with enhanced filtering for database and table discovery, supporting LIKE/NOT LIKE patterns and both ClickHouse and chDB tools.3Apache 2.0
- AlicenseAqualityDmaintenanceA DataOps-focused MCP server for ClickHouse that provides query optimization advice, pipeline latency analysis, and data quality monitoring, with read-only safety.832 PyPIMIT
- AlicenseAqualityBmaintenanceA read-only MCP server for exploratory data analysis across PostgreSQL, MySQL, and ClickHouse databases, providing safe, read-only access with comprehensive analysis capabilities.1084 PyPI6MIT
- FlicenseAqualityDmaintenanceRead-only MCP server for ClickHouse that allows listing databases and tables, describing schemas, and running SELECT queries.4-