¿Qué es ClickHouse MCP Server?
ClickHouse MCP Server es el servidor de código abierto de ClickHouse para ejecutar SQL contra un clúster de ClickHouse. Tiene tres herramientas principales: run_query para SQL, list_databases y list_tables, con detalles de esquema paginados. run_query también admite DESCRIBE y EXPLAIN ESTIMATE, de modo que un agente puede comprobar la salida de una consulta y las lecturas estimadas antes de ejecutarla, y desde la versión 0.7.0 (21 de septiembre de 2026) acepta parámetros de consulta con nombre. Una herramienta opcional de chDB ejecuta SQL con el motor integrado de ClickHouse sobre archivos y URL.
Se instala desde PyPI (uvx mcp-clickhouse) y los datos de conexión, como CLICKHOUSE_HOST, se definen en el entorno. Funciona por stdio de forma predeterminada, o por HTTP o SSE, donde se niega a arrancar sin un bearer token, un proveedor OAuth u OIDC o una exclusión explícita.
Los clientes de ClickHouse Cloud tienen una segunda opción: un servidor remoto gestionado en https://mcp.clickhouse.cloud/mcp con 13 herramientas de solo lectura, inicio de sesión con OAuth o clave de API, que se activa por servicio en la consola de Cloud. El repositorio de código abierto tiene unas 890 estrellas en GitHub y licencia Apache 2.0.
Cómo instalar ClickHouse MCP Server
uvx mcp-clickhouse¿Merece la pena ClickHouse MCP Server?
En el trabajo de analítica, un conjunto pequeño de herramientas es una ventaja. El agente lista bases de datos y tablas, comprueba una consulta con EXPLAIN ESTIMATE para ver cuántas filas y partes leería y después la ejecuta. El modo de solo lectura es el predeterminado y lo aplica el propio ClickHouse mediante readonly=1, no analizando el SQL; activar la escritura requiere CLICKHOUSE_ALLOW_WRITE_ACCESS, y DROP, TRUNCATE, DELETE y UPDATE necesitan además un segundo indicador, CLICKHOUSE_ALLOW_DROP.
La documentación de seguridad es inusualmente completa. El modo HTTP se niega a arrancar sin autenticación. El README advierte de que un archivo .env en cualquier carpeta por encima del paquete instalado puede cambiar la configuración de autenticación, de que los usuarios de solo lectura pueden cancelar otras consultas que se ejecuten con el mismo usuario y de que la vinculación de parámetros no protege la privacidad, porque los valores pueden aparecer en los registros de consultas. Dice claramente que la comprobación de operaciones destructivas protege contra accidentes y que los permisos de ClickHouse son la frontera real.
La carencia es el tamaño de los resultados. Las consultas agotan el tiempo a los 30 segundos por defecto, pero una incidencia abierta indica que un SELECT de 3 millones de filas devolvió 231 MiB dentro de ese plazo, suficiente para desbordar el contexto de cualquier modelo. Hasta que llegue un límite propuesto, la solución es acostumbrarse a usar LIMIT, fijar max_result_rows en el usuario de la base de datos o añadir middleware.
La afirmación anterior de que ClickHouse no ofrece una opción alojada ya no es cierta. El endpoint gestionado de ClickHouse Cloud añade herramientas de solo lectura para servicios, copias de seguridad, ClickPipes y una consulta de costes de la organización de 31 días, sin nada que instalar. El servidor de código abierto sigue siendo el indicado para clústeres autogestionados, chDB o equipos que quieren escritura bajo sus propios controles.
Dónde se gana su sitio
Una analista de producto en una empresa de comercio electrónico de 50 personas que usa ClickHouse Cloud
Responder preguntas puntuales sobre pedidos y embudos sin escribir SQL
Conecta Claude al servidor de solo lectura con un usuario de ClickHouse dedicado y deja que el agente liste tablas y ejecute EXPLAIN ESTIMATE antes de cada SELECT. El servidor es gratis; las consultas se cobran contra el cómputo del servicio de Cloud, desde unos $0,39 por unidad-hora en AWS us-east-1 Enterprise.
Un ingeniero de plataforma de datos que ejecuta ClickHouse autogestionado en Kubernetes
Dar a varios agentes internos acceso compartido y autenticado al almacén de datos
Ejecuta mcp-clickhouse por HTTP con un proveedor OIDC a través de FastMCP, mantén la escritura desactivada y añade middleware que aplique ajustes por inquilino. El aislamiento entre inquilinos tiene que seguir viniendo de los usuarios y roles de ClickHouse.
Una científica de datos que trabaja con archivos Parquet en un portátil
Consultar archivos locales y remotos con SQL sin cargar una base de datos
Instala mcp-clickhouse[chdb] y activa run_chdb_select_query; el motor integrado lee archivos y URL directamente. Sin servidor ni factura de Cloud, pero las consultas de chDB no tienen más protección de escritura en el lado MCP que la que permita el motor.
Antes de decidirte
- Puesta en marcha
- uvx mcp-clickhouse con CLICKHOUSE_HOST, CLICKHOUSE_USER y CLICKHOUSE_PASSWORD en la configuración del cliente; documentado para Claude Desktop y otros clientes stdio. Los usuarios de ClickHouse Cloud pueden activar MCP en un servicio y apuntar un cliente a https://mcp.clickhouse.cloud/mcp.
- Integraciones
- Tres herramientas (run_query, list_databases, list_tables) más run_chdb_select_query como opción. run_query es de solo lectura salvo que se active la escritura; el middleware de FastMCP puede interceptar llamadas para registro o ajustes por usuario.
- Datos y privacidad
- El servidor puede leer todo aquello a lo que tenga permiso su usuario de ClickHouse, así que conviene un usuario dedicado con los mínimos privilegios. Se ejecuta en tu máquina; nada llega a la empresa ClickHouse salvo que tu base de datos esté en ClickHouse Cloud. Los parámetros de consulta pueden aparecer en los registros de consultas de ClickHouse.
- Coste a escala
- El servidor es gratis. En ClickHouse Cloud Enterprise, el cómputo cuesta de $0,33 a $0,52 por unidad-hora (8 GiB, 2 vCPU) y el almacenamiento de $22 a $27,50 por TB-mes, según la región. Los agentes que escanean sin EXPLAIN ESTIMATE pueden despertar servicios inactivos y consumir cómputo.
- Límites
- Tiempo de espera de consulta predeterminado de 30 segundos y 10 hilos de trabajo. Sin tope de filas devueltas (incidencia #223), sin herramientas de administración y sin modo multiusuario integrado. La herramienta de facturación del servidor alojado de Cloud cubre como máximo 31 días por consulta.
Lo bueno
- Solo lectura por defecto, aplicado en el servidor con readonly=1
- Activación aparte para DROP, TRUNCATE, DELETE y UPDATE
- EXPLAIN ESTIMATE permite a los agentes comprobar el coste antes de ejecutar
- El modo HTTP exige un token u OAuth/OIDC
Lo malo
- Sin límite de tamaño de resultado; los SELECT grandes pueden inundar el contexto
- Requiere Python y uv para ejecutar el servidor por tu cuenta
- Sin aislamiento multiusuario ni por inquilino más allá de los permisos de ClickHouse
- El servidor alojado de Cloud es un producto aparte y de solo lectura
Ideal para
Equipos de datos que quieren que un agente responda preguntas a partir de ClickHouse con valores predeterminados seguros.
Alternativas a ClickHouse MCP Server
ClickHouse MCP Server: preguntas frecuentes
- ¿Merece la pena ClickHouse MCP Server?
- Tres herramientas y un modo de solo lectura por defecto lo convierten en un primer servidor de bases de datos seguro para un agente de analítica, siempre que limites tú el tamaño de los resultados. Le damos un 4.2 sobre 5.
- ¿Cuánto cuesta ClickHouse MCP Server?
- Gratis y con licencia Apache-2.0. ClickHouse Cloud se factura aparte (cómputo Enterprise desde unos $0,33 por unidad-hora de 8 GiB) y ofrece una prueba de 30 días con $300 en créditos.
- ¿Qué inconvenientes tiene ClickHouse MCP Server?
- Sin límite de tamaño de resultado; los SELECT grandes pueden inundar el contexto; requiere Python y uv para ejecutar el servidor por tu cuenta; sin aislamiento multiusuario ni por inquilino más allá de los permisos de ClickHouse; el servidor alojado de Cloud es un producto aparte y de solo lectura.
- ¿Para quién es ClickHouse MCP Server?
- Equipos de datos que quieren que un agente responda preguntas a partir de ClickHouse con valores predeterminados seguros.
- ¿Cuánto cuesta ClickHouse MCP Server para un equipo o en producción?
- El servidor es gratis. En ClickHouse Cloud Enterprise, el cómputo cuesta de $0,33 a $0,52 por unidad-hora (8 GiB, 2 vCPU) y el almacenamiento de $22 a $27,50 por TB-mes, según la región. Los agentes que escanean sin EXPLAIN ESTIMATE pueden despertar servicios inactivos y consumir cómputo.
- ¿Es ClickHouse MCP Server seguro para los datos de la empresa?
- El servidor puede leer todo aquello a lo que tenga permiso su usuario de ClickHouse, así que conviene un usuario dedicado con los mínimos privilegios. Se ejecuta en tu máquina; nada llega a la empresa ClickHouse salvo que tu base de datos esté en ClickHouse Cloud. Los parámetros de consulta pueden aparecer en los registros de consultas de ClickHouse.
- ¿Cuáles son las mejores alternativas a ClickHouse MCP Server?
- Las alternativas más cercanas que hemos analizado son Snowflake-managed MCP Server, MCP Toolbox for Databases y Grafana MCP Server.
Respuestas comprobadas el 23 oct 2026.