mcp-clickhousex
Herramienta MCP ClickHouse
Un servidor de solo lectura del Model Context Protocol (MCP) para ClickHouse que admite descubrimiento de metadatos, recursos, consultas SELECT parametrizadas, introspección SHOW, análisis de consultas y modo de instantánea para conjuntos de resultados grandes, con configuración basada en perfiles y aplicación estricta de no-DML/DDL.
Requisitos: Python 3.13+, una instancia de ClickHouse en ejecución y detalles de conexión mediante variables de entorno o un archivo de configuración.
Inicio rápido
Establezca un DSN y ejecute el servidor con 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
Configuración
Todos los ajustes usan el prefijo MCP_CLICKHOUSE. Las variables de entorno planas (p. ej. MCP_CLICKHOUSE_DSN) son la forma directa de configurar el perfil predeterminado cuando se tiene una única conexión. Para varios perfiles, se recomienda el archivo config.json con ámbito de usuario.
Conexión única: configúrela mediante variables de entorno.
# 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"Conexiones múltiples: use el archivo config.json con ámbito de usuario (recomendado). Las variables de entorno también funcionan mediante el prefijo MCP_CLICKHOUSE_PROFILES_<NAME>_ (p. ej. MCP_CLICKHOUSE_PROFILES_WAREHOUSE_DSN).
Unix-like:
~/.config/mcp-clickhousex/config.jsonWindows:
%USERPROFILE%\.config\mcp-clickhousex\config.json
Ejemplo (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"
}
}
}Caracteres especiales en las credenciales: si el nombre de usuario o la contraseña contienen caracteres reservados de URL, codifíquelos con porcentaje en el DSN:
Carácter | Codificación |
|
|
|
|
|
|
|
|
|
|
Por ejemplo, el nombre de usuario admin@org y la contraseña p#ss? se convierten en admin%40org:p%23ss%3F en el DSN: http://admin%40org:p%23ss%3F@host:8123/database.
Herramientas
Las descripciones de las herramientas coinciden con los docstrings de las herramientas de server.py, excepto que el prefijo [ClickHouse] se omite aquí (permanece en los metadatos expuestos por MCP). El texto de los parámetros coincide con cada Field(description=…) de la misma herramienta.
Herramienta | Descripción | Parámetros clave |
| Lista los perfiles configurados. Cada entrada incluye nombre y descripción opcional. | — |
| Obtiene las propiedades del clúster y los límites de ejecución. Devuelve la versión del servidor ClickHouse más los límites aplicados (máx. filas, tiempos de espera) para el perfil. |
|
| Ejecuta SELECT de solo lectura o WITH … SELECT. Una sola sentencia; se rechazan DML, DDL, SET, SYSTEM y similares. Devuelve |
|
| Ejecuta una sentencia de introspección SHOW. Una sentencia por llamada; se rechaza INTO OUTFILE. Se aplican límites interactivos de filas (predeterminado 500, tope máximo 1 000). Mismo tiempo de espera que run_query. |
|
| Explica SELECT de solo lectura o WITH … SELECT. Devuelve texto de plan, pipeline y/o sintaxis. Tipos predeterminados: plan y pipeline. Usa el tiempo de espera de consulta y base de datos opcional; sin límite máximo de filas a diferencia de run_query. |
|
| Lista las bases de datos. Filas de system.databases visibles para la conexión. |
|
| Lista tablas y vistas en una base de datos. Filas de system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes para la planificación de consultas. |
|
| Lista columnas de una tabla o vista. Filas de system.columns para la base de datos y tabla resueltas. |
|
Recursos
El servidor expone el mismo descubrimiento y metadatos que las herramientas anteriores a través de recursos direccionables por URI (jerarquía primero-perfil). La description de cada recurso coincide con la herramienta correspondiente (list_profiles, get_cluster_properties, list_databases, list_tables, list_columns), más etiquetas Src: para los parámetros de ruta URI. Todo el contenido de los recursos es JSON (application/json) excepto las instantáneas que devuelven CSV (text/csv). Use el segmento de ruta default para el perfil o base de datos predeterminado.
Las descripciones de los recursos coinciden con description=… en @mcp.resource en server.py (misma omisión de prefijo que arriba).
URI | Descripción |
| Lista los perfiles configurados. Cada entrada incluye nombre y descripción opcional. |
| Obtiene las propiedades del clúster y los límites de ejecución. Devuelve la versión del servidor ClickHouse más los límites aplicados (máximo de filas, tiempos de espera) para el perfil. Src: profiles. |
| Lista las bases de datos. Filas de system.databases visibles para la conexión. Src: profiles. |
| Lista tablas y vistas en una base de datos. Filas de system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes para la planificación de consultas. Src: profiles, dbs. |
| Lista las columnas de una tabla o vista. Filas de system.columns para la base de datos y tabla resueltas. Src: profiles, dbs, tables. |
| Obtiene una instantánea del resultado de una consulta por ID. Devuelve el resultado completo como una cadena CSV (fila de encabezado + filas de datos). Las entradas caducan después de 7 días. Src: run_query con snapshot=true. |
Seguridad
Solo SQL de solo lectura: run_query permite SELECT / WITH … SELECT; run_show permite una única sentencia SHOW por llamada. INTO OUTFILE no está permitido en run_show. Las consultas interactivas imponen un límite estricto de filas (predeterminado 500, tope máximo 1 000); para extracciones más grandes use snapshot=true (predeterminado 10 000, tope máximo 50 000). Se admiten consultas parametrizadas donde el controlador lo permite (sintaxis %(name)s o {name:Type}). Use variables de entorno para las credenciales de conexión — nunca comprometa secretos.
Ejemplos de host MCP
Fragmentos para clientes MCP comunes usando uvx mcp-clickhousex (no se requiere clonar; asegúrese de que uv esté en su PATH). Reemplace los detalles de conexión según sea necesario.
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"
}
}
}
}Ubicaciones de archivos de configuración: Cursor .cursor/mcp.json, Codex/Copilot/OpenCode varían según el cliente; consulte la documentación MCP de su cliente.
Pruebas
Las pruebas requieren una instancia de ClickHouse en ejecución. El conjunto de pruebas crea una tabla de muestra en la base de datos predeterminada, la llena y la elimina después.
# Run all tests (unit + functional + e2e)
uv run pytest tests/ -vEl arnés de pruebas usa MCP_TEST_CLICKHOUSE_DSN para localizar la instancia de ClickHouse. Si no está configurado, recurre a http://admin:password123@localhost:8123/default. Configure la variable para apuntar las pruebas a un servidor diferente sin afectar su MCP_CLICKHOUSE_DSN de producción:
export MCP_TEST_CLICKHOUSE_DSN="http://user:pass@testhost:8123/default"
uv run pytest tests/ -vHoja de ruta
No hay funciones planificadas en este momento. Abra un issue para sugerir mejoras.
Contribuciones
Abra issues o PRs; siga el estilo existente y agregue pruebas donde corresponda.
Licencia
MIT. Consulte 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-