Cómo conectar ClickHouse a Gemini vía MCP

💡 ¿Sin instalación? Usa cloud.anythingmcp.com directamente. Inicia sesión, pulsa Connectors → ClickHouse, pega tus credenciales, genera una MCP API key y listo. Sin Docker, sin git clone, sin servidor local.

ClickHouse + Gemini

Deja que cualquier agente de IA consulte un servidor ClickHouse o un servicio de ClickHouse Cloud en modo de solo lectura a través de la interfaz HTTP: lista bases de datos, tablas y columnas, lee sentencias CREATE, revisa el tamaño de las tablas, ve las consultas en curso y recientes y ejecuta cualquier SELECT. Cada petición lleva readonly=1, así que es el propio ClickHouse quien rechaza las escrituras.

Requisitos previos

Las instrucciones de configuración completas están incluidas en el conector (visibles en el store al seleccionarlo). Las variables de entorno requeridas:

CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD

Paso 1 — Obtener credenciales

La configuración lleva unos 3 minutos. Necesitas la dirección HTTPS de un servidor ClickHouse o de un servicio de ClickHouse Cloud y un usuario que pueda leer.

1. Pon en CLICKHOUSE_URL la dirección de la interfaz HTTP con su puerto. En ClickHouse Cloud abre el servicio, haz clic en Connect, elige HTTPS y copia el host, por ejemplo https://abc123xyz.europe-west4.gcp.clickhouse.cloud:8443. Autoalojado: https://your-host:8443, o http://your-host:8123 en una red privada. Solo esquema, host y puerto, sin ruta.
2. Crea un usuario dedicado que solo pueda leer, por ejemplo CREATE USER mcp_reader IDENTIFIED BY '...'; GRANT SELECT ON analytics.* TO mcp_reader;. Para clickhouse_table_sizes, clickhouse_running_queries y clickhouse_recent_queries concede además GRANT SELECT ON system.parts, system.processes, system.query_log TO mcp_reader. En ClickHouse Cloud el usuario integrado es default.
3. No le asignes a ese usuario un perfil de ajustes con readonly = 2: el conector fija readonly=1 en cada petición y con readonly = 2 ClickHouse rechaza ese cambio. readonly = 0 o 1 funcionan los dos.
4. Pon el nombre de usuario en CLICKHOUSE_USER y su contraseña en CLICKHOUSE_PASSWORD. Se envían como HTTP Basic auth.
5. Solo ClickHouse Cloud: la IP access list del servicio debe permitir la dirección desde la que llama AnythingMCP.
6. Instala el conector y ejecuta clickhouse_server_info: muestra la versión, el uptime, la zona horaria del servidor, el usuario conectado, su base de datos por defecto y su nivel readonly efectivo.

Qué lee: las bases de datos que el usuario puede ver con su engine y comentario, las tablas y vistas de una base de datos (engine, filas y bytes totales, tamaño legible, comentario), las columnas de una tabla con tipo, expresión por defecto y si forman parte de la clave de partición, de ordenación o primaria, la sentencia CREATE de una tabla o vista (engine, ORDER BY, PARTITION BY, TTL, ajustes, o el SELECT que hay detrás de una vista) y las columnas que clickhouse_search_columns encuentra por nombre en todas las bases de datos. Para la operación: el almacenamiento por tabla según las partes activas, las consultas que se están ejecutando y las consultas terminadas o fallidas del query log. clickhouse_query ejecuta una sentencia de tipo SELECT, WITH, SHOW, DESCRIBE, EXPLAIN o EXISTS.

Qué escribe: nada. Cada petición lleva el ajuste readonly=1, así que ClickHouse rechaza INSERT, ALTER, CREATE, DROP y SET sean cuales sean los permisos del usuario. Como no hay herramientas de escritura, ninguna herramienta viene desactivada al instalar.

Cómo consulta la IA: explora con clickhouse_list_databases, clickhouse_list_tables, clickhouse_describe_table y clickhouse_show_create_table, luego filtra por la clave de ordenación y las columnas de partición, agrega en SQL (count(), sum(), uniq(), quantile(0.95)(x), toStartOfDay(ts)) y termina siempre con LIMIT. Antes de una consulta que pueda recorrer una tabla grande puede ejecutar EXPLAIN o EXPLAIN ESTIMATE. Una consulta es una sola sentencia sin cláusula FORMAT y sin punto y coma final; database fija la base de datos por defecto para los nombres de tabla sin calificar.

Formatos de datos: el formato JSON devuelve meta (nombres y tipos de columna), data (filas), rows (número de filas) y statistics (segundos transcurridos, filas y bytes leídos). clickhouse_query también puede responder en JSONCompact (filas como arrays, más pequeño), CSVWithNames o TabSeparatedWithNames. Los enteros de 64 bits (UInt64, Int64) llegan como cadenas, así que "12345678901" es un número. Los valores DateTime son YYYY-MM-DD hh:mm:ss en la zona horaria del servidor que indica clickhouse_server_info, salvo que el tipo de columna indique otra. Los tamaños de formatReadableSize están en unidades binarias (KiB, MiB, GiB).

Paginación y límites: no hay paginación ni tope de filas aparte de tu LIMIT y del límite de tamaño de respuesta del conector; el resultado completo llega en una sola respuesta, así que mejor agregar que traer filas en bruto. clickhouse_search_columns devuelve hasta 500 coincidencias. clickhouse_recent_queries devuelve las últimas 100 consultas dentro de minutes (60 por defecto). clickhouse_running_queries solo muestra el nodo que responde, en ClickHouse Cloud una réplica del servicio. Un servicio de Cloud inactivo despierta con la primera consulta, lo que puede tardar hasta un minuto.

Errores frecuentes: el cuerpo trae Code: <n>. DB::Exception: .... El código 164 (READONLY) significa que la sentencia escribe o cambia un ajuste. 497 (ACCESS_DENIED, HTTP 403) indica que falta un GRANT, o en ClickHouse Cloud que la IP access list no permite este servidor. 60 (UNKNOWN_TABLE) y 81 (UNKNOWN_DATABASE) indican un nombre equivocado, 62 (SYNTAX_ERROR) SQL incorrecto, 159 o 241 un timeout o un límite de memoria: acota la consulta. 401 o 516 (AUTHENTICATION_FAILED) significa usuario o contraseña incorrectos. Si nada responde en la dirección, normalmente el puerto está mal o CLICKHOUSE_URL lleva una ruta.

El conector no inserta, actualiza ni borra datos, no crea ni modifica tablas y no gestiona servicios de ClickHouse Cloud (arrancar, parar, escalado, copias de seguridad, costes): para eso instala el conector aparte ClickHouse Cloud.

Paso 2 — Instalar el adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Paso 3 — Añadir el conector en Gemini

La URL de tu servidor: en AnythingMCP abre MCP Servers → el servidor donde está este conector y copia su URL (https://cloud.anythingmcp.com/mcp/…). Úsala donde esta guía muestra YOUR_SERVER_ID.

Gemini CLI lee los servidores MCP de ~/.gemini/settings.json (en Windows, %USERPROFILE%\.gemini\settings.json). Añade:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una clave de API MCP en AnythingMCP en MCP Servers → tu servidor → API keys y pégala en lugar de YOUR_MCP_API_KEY.
2. Guarda el archivo y reinicia gemini.
3. Ejecuta /mcp dentro de Gemini CLI (o gemini mcp list en tu terminal): anythingmcp debería aparecer como conectado.
4. Empieza a escribir prompts: Gemini CLI ya puede llamar a las herramientas de ClickHouse.

Herramientas disponibles

Ejemplos de prompts

• "¿Qué bases de datos y tablas hay, y qué tablas ocupan más espacio en disco?"
• "¿Cuántos eventos por día tuvimos en analytics.events en los últimos 30 días?"
• "¿Dónde está una columna como customer_id? Busca en todas las bases de datos."
• "Muéstrame las consultas que fallaron en la última hora con su código de error."
• "¿Cuáles son los 10 países con más ingresos este mes? Revisa primero la clave de ordenación para que la consulta salga barata."

FAQ

¿Dónde busca Gemini CLI los servidores MCP? En ~/.gemini/settings.json para tu usuario, o en .gemini/settings.json dentro de un proyecto. gemini mcp list muestra cada servidor y si se conecta.

Siguientes pasos

• Página del conector
• Conectar a Claude
• Conectar a ChatGPT
• Conectar a Cursor
• Conectar a Meta Muse
• Conectar a Microsoft Copilot