Skip to main content
Glama
mcp-clickhousex

mcp-clickhousex

Herramienta MCP ClickHouse

CI PyPI Python 3.13+ License: MIT

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.py

Related 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.json

  • Windows: %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

#

%23

?

%3F

/

%2F

@

%40

%

%25

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

list_profiles

Lista los perfiles configurados. Cada entrada incluye nombre y descripción opcional.

—

get_cluster_properties

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.

profile — Nombre del perfil; usa el perfil predeterminado si se omite. Fuente: profiles.

run_query

Ejecuta SELECT de solo lectura o WITH … SELECT. Una sola sentencia; se rechazan DML, DDL, SET, SYSTEM y similares. Devuelve {data, row_count} donde data es una cadena CSV RFC 4180. Pasa snapshot=true para persistir el resultado en disco y recibir {snapshot_uri, row_count} en su lugar; obtén el CSV mediante el URI de recurso de snapshot. Límite máximo de filas; el desbordamiento establece truncated y row_limit. Misma validación SQL que analyze_query.

sql (obligatorio) — SELECT de solo lectura o WITH … SELECT. Una sola sentencia; usa db.table o database calificados. Sintaxis de marcador de posición del driver para parámetros. parameters — Parámetros con nombre para marcadores de posición del driver (p. ej. %(name)s o {name:Type}). database — Base de datos predeterminada de la sesión para nombres no calificados. Fuente: databases. profile — Nombre del perfil; usa el perfil predeterminado si se omite. Fuente: profiles. snapshot — Cuando es true, persiste el resultado completo como archivo CSV y devuelve un URI de recurso (chx://snapshots/{id}) en lugar de datos en línea. Úsalo para consultas que puedan superar el límite interactivo de filas (1 000). Se aplican límites de snapshot (predeterminado 10 000 filas, tope máximo 50 000). Las entradas caducan a los 7 días.

run_show

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.

sql (obligatorio) — Una sola sentencia SHOW (p. ej. SHOW DATABASES, SHOW CREATE TABLE). Sin INTO OUTFILE. parameters — Parámetros con nombre para marcadores de posición del driver (p. ej. %(name)s o {name:Type}). database — Base de datos predeterminada de la sesión para nombres no calificados. Fuente: databases. profile — Nombre del perfil; usa el perfil predeterminado si se omite. Fuente: profiles.

analyze_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.

sql (obligatorio) — SELECT de solo lectura o WITH … SELECT para EXPLAIN. Una sola sentencia; misma validación que run_query. parameters — Parámetros con nombre para marcadores de posición del driver (p. ej. %(name)s o {name:Type}). database — Base de datos predeterminada de la sesión para nombres no calificados. Fuente: databases. profile — Nombre del perfil; usa el perfil predeterminado si se omite. Fuente: profiles. types — Variantes de EXPLAIN: plan (índices), pipeline, syntax. Predeterminado: plan y pipeline si se omite.

list_databases

Lista las bases de datos. Filas de system.databases visibles para la conexión.

profile — Nombre del perfil; usa el perfil predeterminado si se omite. Fuente: profiles.

list_tables

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.

database — Base de datos a listar; predeterminada del cliente si se omite. Fuente: databases. profile — Nombre del perfil; usa el perfil predeterminado si se omite. Fuente: profiles.

list_columns

Lista columnas de una tabla o vista. Filas de system.columns para la base de datos y tabla resueltas.

table (obligatorio) — Nombre de tabla o vista, o database.table. Fuente: tables. database — Base de datos cuando table no está calificada; se ignora si table contiene un punto. Predeterminada del cliente si se omite. Fuente: databases. profile — Nombre del perfil; usa el perfil predeterminado si se omite. Fuente: profiles.

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

chx://profiles

Lista los perfiles configurados. Cada entrada incluye nombre y descripción opcional.

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

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.

chx://profiles/{profile}/databases

Lista las bases de datos. Filas de system.databases visibles para la conexión. Src: profiles.

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

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.

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

Lista las columnas de una tabla o vista. Filas de system.columns para la base de datos y tabla resueltas. Src: profiles, dbs, tables.

chx://snapshots/{id}

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/ -v

El 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/ -v

Hoja 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 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