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 접두사를 사용합니다. 플랫(flat) 환경 변수(예: 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를 실행합니다. 단일 문장만 허용하며 DML, DDL, SET, SYSTEM 및 유사한 문장은 거부됩니다. |
|
| SHOW introspection 문장을 실행합니다. 호출당 하나의 문장만 허용하며 INTO OUTFILE은 거부됩니다. 대화형 행 제한이 적용됩니다(기본 500, 상한 1 000). 시간 제한은 run_query와 동일합니다. |
|
| 읽기 전용 SELECT 또는 WITH … SELECT를 EXPLAIN합니다. plan, pipeline 및/또는 syntax 텍스트를 반환합니다. 기본 types는 plan과 pipeline입니다. 쿼리 시간 제한과 선택적 database를 사용하며, 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 문을 허용합니다. run_show에서는 INTO OUTFILE이 허용되지 않습니다. 대화형 쿼리는 엄격한 행 상한(기본 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로드맵
현재 계획된 기능이 없습니다. 개선 사항을 제안하려면 이슈를 열어 주세요.
기여
이슈 또는 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-