ClickHouse

Servidor MCP de ClickHouse

Un servidor MCP para ClickHouse.

Características

Herramientas de ClickHouse

• run_query

  • Ejecuta consultas SQL en tu clúster de ClickHouse.
  • Entrada: query (string): La consulta SQL a ejecutar.
  • Las consultas se ejecutan en modo de solo lectura por defecto (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), pero las escrituras pueden habilitarse explícitamente si es necesario.

• list_databases

  • Lista todas las bases de datos en tu clúster de ClickHouse.

• list_tables

  • Lista las tablas en una base de datos con paginación.
  • Entrada requerida: database (string).
  • Entradas opcionales:
    • like / not_like (string): Aplica filtros LIKE o NOT LIKE a los nombres de las tablas.
    • page_token (string): Token devuelto por una llamada previa para obtener la siguiente página.
    • page_size (int, por defecto 50): Número de tablas devueltas por página.
    • include_detailed_columns (bool, por defecto true): Cuando es false, omite los metadatos de las columnas para respuestas más ligeras, manteniendo el create_table_query completo.
  • Forma de la respuesta:
    • tables: Array de objetos de tabla para la página actual.
    • next_page_token: Pasa este valor de vuelta para obtener la siguiente página, o null cuando no hay más tablas.
    • total_tables: Recuento total de tablas que coinciden con los filtros aplicados.

Herramientas de chDB

• run_chdb_select_query
  • Ejecuta consultas SQL usando el motor embebido de ClickHouse de chDB.
  • Entrada: query (string): La consulta SQL a ejecutar.
  • Consulta datos directamente desde varias fuentes (archivos, URLs, bases de datos) sin procesos ETL.
  • Requiere el extra opcional chdb: pip install 'mcp-clickhouse[chdb]'

Endpoint de Verificación de Salud

Cuando se ejecuta con transporte HTTP o SSE, un endpoint de verificación de salud está disponible en /health. Este endpoint:

• Devuelve 200 OK (cuerpo: OK) si el servidor está saludable y puede conectarse a ClickHouse
• Devuelve 503 Service Unavailable con un mensaje de error genérico si el servidor no puede conectarse a ClickHouse

El endpoint está intencionalmente sin autenticación para que las sondas del orquestador (ej. liveness/readiness de Kubernetes, balanceadores de carga) puedan alcanzarlo sin credenciales. El cuerpo de la respuesta es deliberadamente mínimo para evitar filtrar cadenas de versión del backend o detalles del error; depura los fallos a través de los logs del servidor.

Ejemplo:

curl http://localhost:8000/health
# Response: OK

Seguridad

Autenticación para Transportes HTTP/SSE

Al usar transporte HTTP o SSE, la autenticación es requerida por defecto. El transporte stdio (por defecto) no requiere autenticación ya que solo se comunica a través de entrada/salida estándar.

Se soportan tres modos de autenticación. Elige uno:

Modo	Cuándo usarlo	Variable de entorno
Token de portador estático	Despliegues simples, servicios internos	CLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (vía FastMCP)	Azure Entra, Google, GitHub, WorkOS, etc.	FASTMCP_SERVER_AUTH=<provider-class-path> (+ variables FASTMCP_SERVER_AUTH_* específicas del proveedor)
Deshabilitado	Solo desarrollo local	CLICKHOUSE_MCP_AUTH_DISABLED=true

El inicio falla si ninguna de estas opciones está configurada para los transportes HTTP/SSE.

Configurando la Autenticación

1. Genera un token seguro (puede ser cualquier cadena aleatoria):

   # Using uuidgen (macOS/Linux)
   uuidgen
   
   # Using openssl
   openssl rand -hex 32
   

2. Configura el servidor con el token:

   export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"
   

3. Configura tu cliente MCP para incluir el token en las peticiones:

   Para Claude Desktop con transporte HTTP/SSE:

   {
     "mcpServers": {
       "mcp-clickhouse": {
         "url": "http://127.0.0.1:8000",
         "headers": {
           "Authorization": "Bearer your-generated-token"
         }
       }
     }
   }
   

   Nota: el endpoint /health está intencionalmente sin autenticación (ver Endpoint de Verificación de Salud arriba). Para verificar que la autenticación por token de portador está realmente rechazando peticiones no autenticadas, accede al endpoint MCP mismo, ej. con el Inspector MCP, o haciendo POST de una petición JSON-RPC a /mcp con y sin la cabecera Authorization y confirmando que la llamada no autenticada devuelve 401.

OAuth / OIDC vía FastMCP

Para despliegues en producción con proveedores de identidad (Azure Entra, Google, GitHub, WorkOS, etc.), delega la autenticación a los proveedores de autenticación integrados de FastMCP en lugar de usar un token estático. Establece FASTMCP_SERVER_AUTH a la ruta completa de la clase de un proveedor de autenticación de FastMCP, junto con las variables FASTMCP_SERVER_AUTH_* específicas del proveedor, y deja CLICKHOUSE_MCP_AUTH_TOKEN sin establecer.

Ejemplo (Azure Entra):

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"

Consulta la documentación de FastMCP para la lista completa de proveedores y sus variables de entorno requeridas.

Modo de Desarrollo (Deshabilitando la Autenticación)

Solo para desarrollo y pruebas locales, puedes deshabilitar la autenticación estableciendo:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

ADVERTENCIA: Usa esto solo para desarrollo local. No deshabilites la autenticación cuando el servidor esté expuesto a cualquier red.

Configuración

Este servidor MCP soporta tanto ClickHouse como chDB. Puedes habilitar uno o ambos según tus necesidades.

1. Abre el archivo de configuración de Claude Desktop ubicado en:

   • En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • En Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Añade lo siguiente:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_ROLE": "<clickhouse-role>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Actualiza las variables de entorno para que apunten a tu propio servicio de ClickHouse.

O, si quieres probarlo con el ClickHouse SQL Playground, puedes usar la siguiente configuración:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Para chDB (motor embebido de ClickHouse), añade la siguiente configuración:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

También puedes habilitar tanto ClickHouse como chDB simultáneamente:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

3. Localiza la entrada de comando para uv y reemplázala con la ruta absoluta al ejecutable uv. Esto asegura que se use la versión correcta de uv al iniciar el servidor. En una mac, puedes encontrar esta ruta usando which uv.

4. Reinicia Claude Desktop para aplicar los cambios.

Acceso de Escritura Opcional

Por defecto, este MCP fuerza consultas de solo lectura para que no puedan ocurrir mutaciones accidentales durante la exploración. Para permitir sentencias DDL o INSERT/UPDATE, establece la variable de entorno CLICKHOUSE_ALLOW_WRITE_ACCESS a true. El servidor sigue forzando el modo de solo lectura si la propia instancia de ClickHouse no permite escrituras.

Protección de Operaciones Destructivas

Incluso cuando el acceso de escritura está habilitado (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), las operaciones destructivas (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) requieren una bandera de aceptación adicional por seguridad. Esto previene la eliminación accidental de datos durante la exploración con IA.

Para habilitar operaciones destructivas, establece ambas banderas:

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}

Este enfoque de dos niveles asegura que las eliminaciones accidentales sean muy difíciles:

• Operaciones de escritura (INSERT, UPDATE, CREATE) requieren CLICKHOUSE_ALLOW_WRITE_ACCESS=true
• Operaciones destructivas (DROP, TRUNCATE) requieren adicionalmente CLICKHOUSE_ALLOW_DROP=true

Ejecución Sin uv (Usando Python del Sistema)

Si prefieres usar la instalación de Python del sistema en lugar de uv, puedes instalar el paquete desde PyPI y ejecutarlo directamente:

1. Instala el paquete usando pip:

   python3 -m pip install mcp-clickhouse
   

   Para instalar también el soporte de chDB:

   python3 -m pip install 'mcp-clickhouse[chdb]'
   

   Para actualizar a la última versión:

   python3 -m pip install --upgrade mcp-clickhouse
   

2. Actualiza tu configuración de Claude Desktop para usar Python directamente:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Alternativamente, puedes usar el script instalado directamente:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "mcp-clickhouse",
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Nota: Asegúrate de usar la ruta completa al ejecutable de Python o al script mcp-clickhouse si no están en tu PATH del sistema. Puedes encontrar las rutas usando:

• which python3 para el ejecutable de Python
• which mcp-clickhouse para el script instalado

Middleware Personalizado

Puedes añadir middleware personalizado al servidor MCP sin modificar el código fuente. FastMCP proporciona un sistema de middleware que te permite interceptar y procesar mensajes del protocolo MCP (llamadas a herramientas, lecturas de recursos, prompts, etc.).

Cómo Usarlo

1. Crea un módulo de Python con clases de middleware que extiendan Middleware y una función setup_middleware(mcp):

# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())

2. Establece la variable de entorno MCP_MIDDLEWARE_MODULE al nombre del módulo (sin la extensión .py):

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}

3. Asegúrate de que tu módulo de middleware esté en la ruta de importación de Python (ej., en el mismo directorio donde se ejecuta el servidor MCP, o instalado como un paquete).

Middleware de Ejemplo

Se proporciona un módulo de middleware de ejemplo en example_middleware.py que muestra patrones comunes:

• Registrar todas las peticiones MCP
• Registrar llamadas a herramientas específicamente
• Medir el tiempo de procesamiento de peticiones

Para usar el ejemplo:

"env": {
  "MCP_MIDDLEWARE_MODULE": "example_middleware"
}

Capacidades del Middleware

La clase base Middleware proporciona ganchos para diferentes operaciones MCP:

• on_message(context, call_next) - Llamado para todos los mensajes
• on_request(context, call_next) - Llamado para todas las peticiones
• on_notification(context, call_next) - Llamado para todas las notificaciones
• on_call_tool(context, call_next) - Llamado cuando se ejecuta una herramienta
• on_read_resource(context, call_next) - Llamado cuando se lee un recurso
• on_get_prompt(context, call_next) - Llamado cuando se recupera un prompt
• on_list_tools(context, call_next) - Llamado al listar herramientas
• on_list_resources(context, call_next) - Llamado al listar recursos
• on_list_resource_templates(context, call_next) - Llamado al listar plantillas de recursos
• on_list_prompts(context, call_next) - Llamado al listar prompts

Cada gancho recibe un objeto MiddlewareContext que contiene el mensaje y los metadatos, y una función call_next para continuar el pipeline.

Configuración Dinámica del Cliente vía Estado de Contexto

El middleware puede sobrescribir la configuración del cliente de ClickHouse por petición usando la clave de estado de contexto CLIENT_CONFIG_OVERRIDES_KEY. El servidor fusiona estas sobrescrituras con la configuración base de las variables de entorno.

from fastmcp.server.dependencies import get_context
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

Esto habilita casos de uso avanzados como ajustes dinámicos de tiempo de espera, enrutamiento específico de inquilino, o configuraciones de conexión por usuario.

Desarrollo

1. En el directorio test-services ejecuta docker compose up -d para iniciar el clúster de ClickHouse.

2. Añade las siguientes variables a un archivo .env en la raíz del repositorio.

Nota: El uso del usuario default en este contexto está destinado únicamente para fines de desarrollo local.

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

3. Ejecuta uv sync para instalar las dependencias. Para instalar uv sigue las instrucciones aquí. Luego haz source .venv/bin/activate.

4. Para pruebas fáciles con el Inspector MCP, ejecuta fastmcp dev mcp_clickhouse/mcp_server.py para iniciar el servidor MCP.

5. Para probar con transporte HTTP y el endpoint de verificación de salud:

   # For development, disable authentication
   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main
   
   # Or with authentication (generate a token first)
   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main
   
   # Then in another terminal:
   curl http://localhost:8000/health
   

Variables de Entorno

La configuración se divide en grupos independientes. Mezclarlos es una causa común de fallos de conexión difíciles de depurar:

Grupo	Variables	Controla
Conexión a la base de datos ClickHouse	CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, …	Cómo este servidor MCP se conecta a tu clúster de ClickHouse a través de la interfaz HTTP
Servidor MCP / transporte	CLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*	Transporte MCP, autenticación y límites de ejecución de la herramienta de consulta
Middleware / chDB	MCP_MIDDLEWARE_MODULE, CHDB_*	Extensiones opcionales

[!IMPORTANTE] Variables como CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY y CLICKHOUSE_PORT aplican solo a la conexión de la base de datos ClickHouse. No configuran TLS, puertos o autenticación para el endpoint del protocolo MCP.

Ejemplo: si el servidor MCP se ejecuta en Kubernetes detrás de un ingress que termina TLS, eso es una preocupación del transporte MCP. Mantén CLICKHOUSE_SECURE alineado con cómo el pod alcanza a ClickHouse mismo (HTTPS → true, HTTP plano → false). Establecer CLICKHOUSE_SECURE=false porque el servidor MCP está detrás de un ingress hará que el servidor marque a ClickHouse sobre HTTP—a menudo contra un puerto solo HTTPS—y produzca errores opacos HTTP/TLS en los logs del servidor.

Conexión a la base de datos ClickHouse

Estas variables configuran el cliente HTTP clickhouse-connect y el comportamiento de las herramientas respaldadas por ClickHouse como run_query, list_databases y list_tables.

Variables obligatorias

• CLICKHOUSE_HOST: El nombre de host de tu servidor ClickHouse (extremo de la base de datos, no la dirección de enlace del servidor MCP)
• CLICKHOUSE_USER: El nombre de usuario para la autenticación de ClickHouse
• CLICKHOUSE_PASSWORD: La contraseña para la autenticación de ClickHouse

[!CAUTION] Es importante tratar a tu usuario de base de datos MCP como lo harías con cualquier cliente externo que se conecte a tu base de datos, otorgando solo los privilegios mínimos necesarios para su funcionamiento. Se debe evitar estrictamente el uso de usuarios predeterminados o administrativos en todo momento.

Variables opcionales

• CLICKHOUSE_PORT: Puerto de la interfaz HTTP de tu servidor ClickHouse
  • Predeterminado: 8443 si CLICKHOUSE_SECURE=true, 8123 si CLICKHOUSE_SECURE=false
  • Normalmente no es necesario configurarlo a menos que se use un puerto no estándar
  • Debe ser un puerto de interfaz HTTP, no el puerto del protocolo TCP nativo usado por clickhouse-client
  • Valores comunes:
    • HTTP: 8123 (plano) / 8443 (TLS) — usado por este servidor y ClickHouse Cloud HTTPS
    • TCP nativo (no compatible aquí): 9000 (plano) / 9440 (TLS) — usado por clickhouse-client
  • Si el servidor responde con Port 9000 is for clickhouse-client program, estás apuntando al protocolo nativo; cambia al puerto HTTP (8123/8443 o la asignación HTTP de tu despliegue)
• CLICKHOUSE_ROLE: El rol de ClickHouse a usar para la autenticación
  • Predeterminado: Ninguno
  • Configúralo si tu usuario requiere un rol específico
• CLICKHOUSE_SECURE: Habilitar HTTPS para la conexión a la base de datos ClickHouse (no para clientes MCP)
  • Predeterminado: "true"
  • Configúralo como "false" solo cuando el servidor MCP llegue a ClickHouse a través de HTTP plano (típico para Docker Compose local en el puerto 8123)
  • Deja "true" para ClickHouse Cloud y cualquier extremo de base de datos HTTPS, incluso si el propio servidor MCP se expone a través de HTTP, stdio o un ingreso que termina TLS por separado
  • No hacer coincidir esta bandera con el puerto de la base de datos (por ejemplo, CLICKHOUSE_SECURE=false contra el puerto 8443) es un error de configuración frecuente y generalmente se manifiesta como errores confusos del cliente HTTP en lugar de un mensaje claro de "esquema incorrecto"
• CLICKHOUSE_VERIFY: Habilitar/deshabilitar la verificación del certificado SSL para la conexión HTTPS de ClickHouse
  • Predeterminado: "true"
  • Configúralo como "false" para deshabilitar la verificación del certificado (no recomendado para producción)
  • Certificados TLS: El paquete usa el almacén de confianza de tu sistema operativo para la verificación del certificado TLS a través de truststore. Llamamos a truststore.inject_into_ssl() al inicio para asegurar un manejo adecuado del certificado. El comportamiento SSL predeterminado de Python se usa como respaldo solo si ocurre un error inesperado.
• CLICKHOUSE_SERVER_HOST_NAME: Nombre de host del servidor para anulación de SNI y validación de certificado en la conexión de ClickHouse
  • Predeterminado: Ninguno (usa el nombre de host de la conexión)
  • Esto es útil al conectarse a través de proxies o balanceadores de carga donde el nombre de host del certificado difiere del nombre de host de la conexión. Cuando se configura, este nombre de host se usará tanto para SNI (Indicación del Nombre del Servidor) durante el handshake TLS como para la validación del nombre de host del certificado.
• CLICKHOUSE_PROXY_PATH: Prefijo de ruta URL para el extremo HTTP de ClickHouse
  • Predeterminado: Ninguno
  • Configúralo cuando la interfaz HTTP de ClickHouse esté expuesta detrás de un proxy inverso bajo un prefijo de ruta (por ejemplo, /clickhouse)
• CLICKHOUSE_CONNECT_TIMEOUT: Tiempo de espera de conexión en segundos para el cliente de ClickHouse
  • Predeterminado: "30"
  • Aumenta este valor si experimentas tiempos de espera de conexión
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Tiempo de espera de envío/recepción en segundos para el cliente de ClickHouse
  • Predeterminado: "300"
  • Aumenta este valor para consultas de larga duración
• CLICKHOUSE_DATABASE: Base de datos ClickHouse predeterminada a usar
  • Predeterminado: Ninguno (usa el predeterminado del servidor)
  • Configúralo para conectarse automáticamente a una base de datos específica
• CLICKHOUSE_ENABLED: Habilitar/deshabilitar las herramientas de base de datos ClickHouse
  • Predeterminado: "true"
  • Configúralo como "false" para deshabilitar las herramientas de ClickHouse cuando se usa solo chDB
• CLICKHOUSE_ALLOW_WRITE_ACCESS: Permitir operaciones de escritura (DDL y DML) contra ClickHouse
  • Predeterminado: "false"
  • Configúralo como "true" para permitir operaciones DDL (CREATE, ALTER, DROP) y DML (INSERT, UPDATE, DELETE)
  • Cuando está deshabilitado (predeterminado), las consultas se ejecutan con la configuración readonly=1 para prevenir modificaciones de datos
• CLICKHOUSE_ALLOW_DROP: Permitir operaciones destructivas (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
  • Predeterminado: "false"
  • Solo tiene efecto cuando CLICKHOUSE_ALLOW_WRITE_ACCESS=true también está configurado
  • Configúralo como "true" para permitir explícitamente operaciones destructivas DROP y TRUNCATE
  • Esta es una característica de seguridad para prevenir la eliminación accidental de datos durante la exploración de IA

Servidor MCP y transporte

Estas variables controlan el proceso MCP en sí, incluyendo transporte, autenticación y límites de ejecución de herramientas de consulta. Son independientes de la configuración de la base de datos ClickHouse anterior. Consulta también Autenticación para transportes HTTP/SSE.

• CLICKHOUSE_MCP_SERVER_TRANSPORT: Establece el método de transporte para el servidor MCP
  • Predeterminado: "stdio"
  • Opciones válidas: "stdio", "http", "sse". Esto es útil para el desarrollo local con herramientas como MCP Inspector.
  • stdio es típico para Claude Desktop; http/sse exponen un oyente de red (host/puerto de enlace abajo)
• CLICKHOUSE_MCP_BIND_HOST: Host al que enlazar el servidor MCP cuando se usa transporte HTTP o SSE
  • Predeterminado: "127.0.0.1"
  • Configúralo como "0.0.0.0" para enlazar a todas las interfaces de red (útil para Docker o acceso remoto)
  • Solo se usa cuando el transporte es "http" o "sse" — no relacionado con CLICKHOUSE_HOST
• CLICKHOUSE_MCP_BIND_PORT: Puerto al que enlazar el servidor MCP cuando se usa transporte HTTP o SSE
  • Predeterminado: "8000"
  • Solo se usa cuando el transporte es "http" o "sse" — no relacionado con CLICKHOUSE_PORT
• CLICKHOUSE_MCP_QUERY_TIMEOUT: Tiempo de espera en segundos para las herramientas de consulta
  • Predeterminado: "30"
  • Auméntalo si ves errores Query timed out after ... para consultas pesadas
• CLICKHOUSE_MCP_AUTH_TOKEN: Token de portador estático para transportes HTTP/SSE
  • Predeterminado: Ninguno
  • Uno de CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH o CLICKHOUSE_MCP_AUTH_DISABLED=true es obligatorio para transportes HTTP/SSE
  • Genera usando uuidgen o openssl rand -hex 32
  • Los clientes deben enviar este token en el encabezado Authorization: Bearer <token>
• FASTMCP_SERVER_AUTH: Delegar la autenticación a un proveedor de autenticación FastMCP
  • Predeterminado: Ninguno
  • El valor es la ruta de clase completa de una subclase AuthProvider, por ejemplo, fastmcp.server.auth.providers.azure.AzureProvider o fastmcp.server.auth.providers.google.GoogleProvider
  • Cuando se configura, FastMCP carga automáticamente el proveedor desde sus propias variables de entorno FASTMCP_SERVER_AUTH_*; deja CLICKHOUSE_MCP_AUTH_TOKEN sin configurar en este modo
• CLICKHOUSE_MCP_AUTH_DISABLED: Deshabilitar la autenticación para transportes HTTP/SSE
  • Predeterminado: "false" (la autenticación está habilitada)
  • Configúralo como "true" para deshabilitar la autenticación solo para desarrollo/pruebas locales
  • ADVERTENCIA: Úsalo solo para desarrollo local. No lo deshabilites cuando esté expuesto a redes

Variables de Middleware

• MCP_MIDDLEWARE_MODULE: Nombre del módulo Python que contiene middleware personalizado para inyectar en el servidor MCP
  • Predeterminado: Ninguno (no se carga middleware)
  • Configúralo con el nombre del módulo (sin la extensión .py) de tu módulo de middleware
  • El módulo debe proporcionar una función setup_middleware(mcp)
  • Consulta Middleware Personalizado para detalles y ejemplos

Variables de chDB

• CHDB_ENABLED: Habilitar/deshabilitar la funcionalidad de chDB
  • Predeterminado: "false"
  • Configúralo como "true" para habilitar las herramientas de chDB
  • Requiere instalar el extra opcional: mcp-clickhouse[chdb]
• CHDB_DATA_PATH: La ruta al directorio de datos de chDB
  • Predeterminado: ":memory:" (base de datos en memoria)
  • Usa :memory: para base de datos en memoria
  • Usa una ruta de archivo para almacenamiento persistente (por ejemplo, /path/to/chdb/data)

Errores comunes de configuración

• CLICKHOUSE_SECURE vs MCP / TLS de ingreso — Desactivar CLICKHOUSE_SECURE porque el servidor MCP se encuentra detrás de un ingreso de Kubernetes, un proxy inverso, o se accede a través de HTTP plano no deshabilita el TLS de la base de datos; solo cambia cómo este proceso se conecta a ClickHouse. Configura el TLS de ingreso por separado de la configuración del cliente de base de datos.
• Puertos de protocolo nativo — CLICKHOUSE_PORT debe apuntar a la interfaz HTTP de ClickHouse (8123/8443 por defecto). Los puertos 9000/9440 son para el protocolo TCP nativo (clickhouse-client) y no funcionarán con este servidor.
• Confusión de host — CLICKHOUSE_HOST es el nombre de host de la base de datos. CLICKHOUSE_MCP_BIND_HOST es solo la dirección en la que escucha el servidor HTTP/SSE MCP.

Configuraciones de ejemplo

Para desarrollo local con Docker:

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

Para ClickHouse Cloud:

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

Para ClickHouse SQL Playground:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

Solo para chDB (en memoria):

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH defaults to :memory:

Para chDB con almacenamiento persistente:

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
CHDB_DATA_PATH=/path/to/chdb/data

Para MCP Inspector o acceso remoto con transporte HTTP:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)

Para desarrollo local con transporte HTTP (autenticación deshabilitada):

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!

Al usar transporte HTTP, el servidor se ejecutará en el puerto configurado (predeterminado 8000). Por ejemplo, con la configuración anterior:

• Extremo MCP: http://localhost:4200/mcp
• Verificación de estado: http://localhost:4200/health

Puedes configurar estas variables en tu entorno, en un archivo .env, o en la configuración de Claude Desktop:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
        "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
        "CLICKHOUSE_MCP_BIND_PORT": "8000"
      }
    }
  }
}

Nota: La configuración de host y puerto de enlace solo se usa cuando el transporte está configurado como "http" o "sse".

Ejecución de pruebas

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only

Resumen de YouTube