ClickHouse MCP Server

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 la escritura se puede habilitar explícitamente si es necesario.

• list_databases

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

• list_tables

  • Lista las tablas de una base de datos con paginación.

  • Entrada obligatoria: 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 anterior 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 la consulta create_table_query completa.

  • 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: número total de tablas que coinciden con los filtros proporcionados.

Herramientas de chDB

• run_chdb_select_query

  • Ejecuta consultas SQL usando el motor ClickHouse integrado 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 comprobación de salud

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

• Devuelve 200 OK (cuerpo: OK) si el servidor está sano y puede conectarse a ClickHouse

• Devuelve 503 Service Unavailable con un mensaje de error genérico si el servidor no puede conectarse a ClickHouse

Las peticiones GET y HEAD al endpoint no están autenticadas a propósito y están exentas de la validación de Host y Origin para que las sondas del orquestador (p. ej. sondeos de liveness/readiness de Kubernetes, balanceadores de carga) puedan usar IPs de pod o de destino asignadas en tiempo de ejecución sin configuración adicional. /health está reservado y no puede usarse como ruta de transporte MCP. El cuerpo de la respuesta es deliberadamente mínimo para evitar filtrar cadenas de versión del backend o detalles de error; depura los fallos a través de los registros del servidor.

Ejemplo:

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

Related MCP server: ClickHouse MCP Server

Seguridad

Autenticación para transportes HTTP/SSE

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

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

El arranque falla si no se configura ninguna de estas opciones para los transportes HTTP/SSE.

Configuración de 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 que incluya 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 no está autenticado a propósito (consulta Endpoint de comprobación de salud más arriba). Para verificar que la autenticación con token de portador está rechazando realmente las peticiones no autenticadas, prueba el propio endpoint MCP, por ejemplo con el MCP Inspector, o enviando 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 en los proveedores de autenticación integrados de FastMCP en lugar de usar un token estático. Establece FASTMCP_SERVER_AUTH en la ruta de clase completa 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 definir.

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 ver la lista completa de proveedores y sus variables de entorno necesarias.

Modo de desarrollo (deshabilitar la autenticación)

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

export CLICKHOUSE_MCP_AUTH_DISABLED=true
export CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

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 admite tanto ClickHouse como chDB. Puedes habilitar uno u otro, 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 ClickHouse integrado), 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 ClickHouse y chDB a la vez:

{
  "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 de uv y sustitúyela por la ruta absoluta al ejecutable de uv. Esto garantiza que se use la versión correcta de uv al iniciar el servidor. En un Mac, puedes encontrar esta ruta usando which uv.

4. Reinicia Claude Desktop para aplicar los cambios.

Acceso de escritura opcional

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

Protección contra operaciones destructivas

Incluso cuando el acceso de escritura está habilitado (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), las operaciones destructivas requieren una bandera de aceptación adicional por seguridad. La comprobación cubre cualquier sentencia DROP (incluidas las cláusulas ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN), cualquier TRUNCATE, DELETE y UPDATE (tanto las sentencias ligeras como las mutaciones ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE), REPLACE TABLE, CREATE OR REPLACE, ALTER TABLE ... REPLACE PARTITION, ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION y DETACH ... PERMANENTLY. Las palabras clave dentro de literales de cadena, identificadores entre comillas y comentarios SQL se ignoran, por lo que ni activan la comprobación ni ocultan una sentencia a la misma.

Esta comprobación se ejecuta en el servidor MCP y es una protección de mejor esfuerzo contra accidentes. No es un límite de seguridad. El límite de seguridad son los permisos del usuario de ClickHouse. El modo de solo lectura (el predeterminado) se aplica en el lado del servidor mediante readonly=1. La barrera de operaciones destructivas no se aplica en el servidor.

Para el modo de escritura, asigna al servidor MCP un usuario de ClickHouse dedicado con solo los privilegios que necesite:

CREATE USER mcp_agent IDENTIFIED BY '...';
GRANT SELECT, INSERT, CREATE TABLE, ALTER ADD COLUMN ON mydb.* TO mcp_agent;

Cualquier sentencia fuera de estos permisos falla entonces en el lado del servidor con ACCESS_DENIED, independientemente de las banderas de MCP. Los ajustes del servidor max_table_size_to_drop y max_partition_size_to_drop también pueden limitar el radio del daño si se fijan con restricciones de ajustes.

Para habilitar las operaciones destructivas, establece ambas banderas:

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

Este enfoque de dos niveles dificulta la eliminación accidental:

• Operaciones de escritura (INSERT, CREATE, ALTER ADD COLUMN) requieren CLICKHOUSE_ALLOW_WRITE_ACCESS=true

• Operaciones destructivas (DROP, TRUNCATE, DELETE, UPDATE y el resto de la lista anterior) requieren además 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 los 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 (p. ej., en el mismo directorio donde se ejecuta el servidor MCP, o instalado como paquete).

Ejemplo de middleware

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

• Registrar todas las peticiones MCP

• Registrar las llamadas a herramientas específicamente

• Medir el tiempo de procesamiento de las peticiones

Para usar el ejemplo:

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

Capacidades del middleware

La clase base Middleware proporciona hooks para diferentes operaciones de MCP:

• on_message(context, call_next) - Se llama para todos los mensajes

• on_request(context, call_next) - Se llama para todas las peticiones

• on_notification(context, call_next) - Se llama para todas las notificaciones

• on_call_tool(context, call_next) - Se llama cuando se ejecuta una herramienta

• on_read_resource(context, call_next) - Se llama cuando se lee un recurso

• on_get_prompt(context, call_next) - Se llama cuando se recupera un prompt

• on_list_tools(context, call_next) - Se llama al listar herramientas

• on_list_resources(context, call_next) - Se llama al listar recursos

• on_list_resource_templates(context, call_next) - Se llama al listar plantillas de recursos

• on_list_prompts(context, call_next) - Se llama al listar prompts

Cada hook 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 mediante el 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 combina 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 permite casos de uso avanzados como ajustes dinámicos de tiempo de espera, enrutamiento específico por inquilino o ajustes de conexión por usuario.

El valor de estado debe ser un diccionario. Los valores anidados de settings y generic_args deben ser mapeos y se fusionan con la configuración base. Los valores no válidos hacen fallar la llamada a la herramienta antes de que se cree un cliente de ClickHouse. CLICKHOUSE_ROLE permanece activo a menos que la anulación proporcione explícitamente settings.role. Las claves de nivel superior role y ch_role, así como las mismas claves dentro de generic_args, se rechazan.

Trate estas anulaciones como entrada de middleware de confianza. El middleware debe autenticar y autorizar los valores derivados de la solicitud antes de establecerlos. Un rol de ClickHouse por solicitud es configuración de conexión, no un límite de autorización de inquilino (tenant). Aplique el aislamiento de inquilinos con usuarios, roles y permisos (grants) de ClickHouse.

Desarrollo

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

2. Añada 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 a fines de desarrollo local.

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

3. Ejecute uv sync para instalar las dependencias. Para instalar uv, siga las instrucciones aquí. Luego ejecute source .venv/bin/activate.

4. Para probar fácilmente con MCP Inspector, ejecute fastmcp dev mcp_clickhouse/mcp_server.py para iniciar el servidor MCP.

5. Para probar con el transporte HTTP y el endpoint de comprobación de estado (health check):

   # For development, disable authentication
   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000 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:

[!IMPORTANT] Variables como CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY y CLICKHOUSE_PORT se aplican únicamente a la conexión con la base de datos ClickHouse. No configuran TLS, puertos ni 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 un asunto del transporte MCP. Mantenga CLICKHOUSE_SECURE alineado con la forma en que el pod llega al propio ClickHouse (HTTPS → true, HTTP simple → false). Establecer CLICKHOUSE_SECURE=false porque el servidor MCP está detrás de un ingress hará que el servidor se conecte a ClickHouse por HTTP —a menudo contra un puerto exclusivo de HTTPS— y producirá errores HTTP/TLS opacos en los registros del servidor.

Conexión a la base de datos ClickHouse

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

Variables Obligatorias

• CLICKHOUSE_HOST: El nombre de host de su servidor ClickHouse (endpoint de la base de datos, no la dirección de enlace del servidor MCP)

• CLICKHOUSE_USER: El nombre de usuario para la autenticación en ClickHouse

• CLICKHOUSE_PASSWORD: La contraseña para la autenticación en ClickHouse

[!CAUTION] Es importante tratar a su usuario de base de datos MCP como lo haría con cualquier cliente externo que se conecte a su base de datos, concediendo únicamente los privilegios mínimos necesarios para su funcionamiento. El uso de usuarios por defecto o administrativos debe evitarse estrictamente en todo momento.

Variables Opcionales

• CLICKHOUSE_PORT: Puerto de la interfaz HTTP de su servidor ClickHouse

  • Valor por defecto: 8443 si CLICKHOUSE_SECURE=true, 8123 si CLICKHOUSE_SECURE=false

  • Normalmente no es necesario configurarlo a menos que se utilice un puerto no estándar

  • Debe ser un puerto de la interfaz HTTP, no el puerto del protocolo TCP nativo utilizado por clickhouse-client

  • Valores comunes:

    • HTTP: 8123 (sin TLS) / 8443 (TLS) — utilizado por este servidor y por ClickHouse Cloud HTTPS

    • TCP nativo (no compatible aquí): 9000 (sin TLS) / 9440 (TLS) — utilizado por clickhouse-client

  • Si el servidor responde con Port 9000 is for clickhouse-client program, está apuntando al protocolo nativo; cambie al puerto HTTP (8123/8443 o la asignación HTTP de su despliegue)

• CLICKHOUSE_ROLE: El rol de ClickHouse que se utilizará para la autenticación

  • Valor por defecto: None

  • Configúrelo si su usuario requiere un rol específico

• CLICKHOUSE_SECURE: Habilite HTTPS para la conexión a la base de datos ClickHouse (no para los clientes MCP)

  • Valor por defecto: "true"

  • Establézcalo en "false" solo cuando el servidor MCP llegue a ClickHouse por HTTP simple (típico en Docker Compose local en el puerto 8123)

  • Déjelo en "true" para ClickHouse Cloud y cualquier endpoint de base de datos HTTPS, incluso si el propio servidor MCP se expone por HTTP, stdio o un ingress que termina TLS por separado

  • No hacer coincidir este indicador con el puerto de la base de datos (p. ej., CLICKHOUSE_SECURE=false contra el puerto 8443) es un error de configuración frecuente que suele manifestarse como errores confusos del cliente HTTP en lugar de un mensaje claro de «esquema incorrecto»

• CLICKHOUSE_VERIFY: Habilite/deshabilite la verificación de certificados SSL para la conexión HTTPS a ClickHouse

  • Valor por defecto: "true"

  • Establézcalo en "false" para deshabilitar la verificación de certificados (no recomendado para producción)

  • Certificados TLS: el paquete utiliza el almacén de confianza de su sistema operativo para la verificación de certificados TLS mediante truststore. Llamamos a truststore.inject_into_ssl() al inicio para garantizar un manejo correcto de los certificados. El comportamiento SSL predeterminado de Python se utiliza como respaldo solo si se produce un error inesperado.

• CLICKHOUSE_SERVER_HOST_NAME: Nombre de host del servidor para la anulación de SNI y la validación de certificados en la conexión a ClickHouse

  • Valor por defecto: None (utiliza el nombre de host de la conexión)

  • 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 establece, este nombre de host se utilizará tanto para SNI (Server Name Indication) durante el handshake TLS como para la validación del nombre de host del certificado.

• CLICKHOUSE_PROXY_PATH: Prefijo de ruta URL para el endpoint HTTP de ClickHouse

  • Valor por defecto: None

  • Configúrelo 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

  • Valor por defecto: "30"

  • Aumente este valor si experimenta 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

  • Valor por defecto: "300"

  • Aumente este valor para consultas de larga duración

• CLICKHOUSE_DATABASE: Base de datos ClickHouse predeterminada a utilizar

  • Valor por defecto: None (utiliza la predeterminada del servidor)

  • Configúrelo para conectarse automáticamente a una base de datos específica

• CLICKHOUSE_ENABLED: Habilite/deshabilite las herramientas de base de datos de ClickHouse

  • Valor por defecto: "true"

  • Establézcalo en "false" para deshabilitar las herramientas de ClickHouse cuando se utilice solo chDB

• CLICKHOUSE_ALLOW_WRITE_ACCESS: Permita operaciones de escritura (DDL y DML) contra ClickHouse

  • Valor por defecto: "false"

  • Establézcalo en "true" para permitir DDL y DML no destructivos (CREATE, INSERT, ALTER ADD COLUMN). Las sentencias destructivas además necesitan CLICKHOUSE_ALLOW_DROP=true

  • Cuando está deshabilitado (valor por defecto), las consultas se ejecutan con el ajuste readonly=1 para evitar modificaciones de datos

• CLICKHOUSE_ALLOW_DROP: Permita operaciones destructivas (cualquier DROP o TRUNCATE, DELETE y UPDATE incluidas las variantes de ALTER TABLE, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION, y DETACH ... PERMANENTLY)

  • Valor por defecto: "false"

  • Solo tiene efecto cuando también se establece CLICKHOUSE_ALLOW_WRITE_ACCESS=true

  • Esta compuerta es una protección contra accidentes de buena fe (best-effort) en el servidor MCP, no un límite de seguridad. Restrinja los permisos (grants) del usuario de ClickHouse para una aplicación real (consulte Protección de operaciones destructivas)

Servidor MCP y transporte

Estas variables controlan el propio proceso MCP, incluidos el transporte, la autenticación y los límites de ejecución de las herramientas de consulta. Son independientes de los ajustes de la base de datos ClickHouse mencionados anteriormente. Consulte también Autenticación para transportes HTTP/SSE.

• CLICKHOUSE_MCP_SERVER_TRANSPORT: Establece el método de transporte para el servidor MCP

  • Valor por defecto: "stdio"

  • Opciones válidas: "stdio", "http", "sse". Esto es útil para el desarrollo local con herramientas como MCP Inspector.

  • stdio es lo habitual para Claude Desktop; http/sse exponen un listener de red (host/puerto de enlace más abajo)

• CLICKHOUSE_MCP_BIND_HOST: Host al que enlazar el servidor MCP cuando se usa transporte HTTP o SSE

  • Valor por defecto: "127.0.0.1"

  • Configúrelo en "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 está relacionado con CLICKHOUSE_HOST

• CLICKHOUSE_MCP_BIND_PORT: Puerto al que enlazar el servidor MCP cuando se usa transporte HTTP o SSE

  • Valor por defecto: "8000"

  • Solo se usa cuando el transporte es "http" o "sse" — no está relacionado con CLICKHOUSE_PORT

• CLICKHOUSE_MCP_QUERY_TIMEOUT: Tiempo de espera (timeout) en segundos para las herramientas de consulta

  • Valor por defecto: "30"

  • Auméntelo si ve errores Query timed out after ... para consultas pesadas

• CLICKHOUSE_MCP_AUTH_TOKEN: Token bearer estático para transportes HTTP/SSE

  • Valor por defecto: Ninguno

  • Uno de CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH o CLICKHOUSE_MCP_AUTH_DISABLED=true es obligatorio para transportes HTTP/SSE

  • Genérelo con uuidgen o openssl rand -hex 32

  • Los clientes deben enviar este token en la cabecera Authorization: Bearer <token>

• FASTMCP_SERVER_AUTH: Delegar la autenticación a un proveedor de autenticación FastMCP

  • Valor por defecto: Ninguno

  • El valor es la ruta de clase completa de una subclase de AuthProvider, p. ej. fastmcp.server.auth.providers.azure.AzureProvider o fastmcp.server.auth.providers.google.GoogleProvider

  • Cuando se establece, FastMCP carga automáticamente el proveedor desde sus propias variables de entorno FASTMCP_SERVER_AUTH_*; deje CLICKHOUSE_MCP_AUTH_TOKEN sin establecer en este modo

• CLICKHOUSE_MCP_AUTH_DISABLED: Deshabilitar la autenticación para transportes HTTP/SSE

  • Valor por defecto: "false" (la autenticación está habilitada)

  • Configúrelo en "true" para deshabilitar la autenticación solo para desarrollo/pruebas locales

  • ADVERTENCIA: Úselo solo para desarrollo local. No lo deshabilite cuando esté expuesto a redes

• CLICKHOUSE_MCP_ALLOWED_HOSTS: Valores de cabecera Host separados por comas a los que responde el servidor HTTP/SSE

  • Valor por defecto para un enlace de loopback: formas sin puerto y con cualquier puerto de 127.0.0.1, localhost y [::1]

  • Si se establece, el valor debe contener al menos una entrada Host.

  • Una dirección de enlace concreta no loopback usa por defecto esa dirección y el puerto configurado. Un enlace comodín como 0.0.0.0 o :: requiere un valor explícito no vacío porque el Host público no se puede inferir.

  • La validación de Host es una defensa en profundidad contra el DNS rebinding. La validación de Origin que aparece más abajo la exige MCP por separado.

  • Las entradas son exactas (localhost:8000) o aceptan cualquier puerto (localhost:*). Ejemplo: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

  • La forma host:* solo coincide con valores que incluyen un puerto. Un Host sin puerto (un despliegue en puerto estándar donde el cliente omite :80/:443) también debe aparecer como una entrada exacta sin puerto (example.com).

  • Las solicitudes con una cabecera Host que no coincide o falta reciben 421 Misdirected Request. Las solicitudes GET y HEAD a /health están exentas de la validación de Host y Origin para que las sondas del orquestador sigan funcionando.

  • Detrás de un proxy inverso, indique el valor de Host que reenvía el proxy. Establezca una lista explícita cuando un lanzador como fastmcp run sobrescriba la dirección de enlace para el acceso remoto.

• CLICKHOUSE_MCP_ALLOWED_ORIGINS: Valores de cabecera Origin separados por comas aceptados en HTTP/SSE

  • Valor por defecto: Ninguno, lo que rechaza toda solicitud que lleve una cabecera Origin

  • MCP exige la validación de Origin para las conexiones de transporte HTTP/SSE. Las solicitudes sin Origin se aceptan porque los clientes MCP que no son de navegador normalmente la omiten. Un Origin que no coincide recibe 403 Forbidden. El endpoint /health está exento como se ha descrito anteriormente.

  • Las entradas son exactas (http://localhost:3000) o aceptan cualquier puerto (http://localhost:*). Al igual que con los hosts, la forma con cualquier puerto solo coincide con orígenes que incluyen un puerto; un origen en puerto estándar (https://app.example.com) debe indicarse exactamente.

Variables de middleware

• MCP_MIDDLEWARE_MODULE: Nombre del módulo Python que contiene el middleware personalizado que se inyecta en el servidor MCP

  • Valor por defecto: Ninguno (no se carga middleware)

  • Configúrelo con el nombre del módulo (sin la extensión .py) de su módulo de middleware

  • El módulo debe proporcionar una función setup_middleware(mcp)

  • Consulte Middleware personalizado para obtener detalles y ejemplos

Variables de chDB

• CHDB_ENABLED: Habilita/deshabilita la funcionalidad de chDB

  • Valor por defecto: "false"

  • Configúrelo en "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

  • Valor por defecto: ":memory:" (base de datos en memoria)

  • Use :memory: para una base de datos en memoria

  • Use una ruta de archivo para almacenamiento persistente (p. ej., /path/to/chdb/data)

Errores comunes de configuración

• CLICKHOUSE_SECURE frente a TLS de MCP / ingress — Desactivar CLICKHOUSE_SECURE porque el servidor MCP está detrás de un ingress de Kubernetes, un proxy inverso, o se accede a él por HTTP simple no deshabilita el TLS de la base de datos; solo cambia cómo este proceso se conecta a ClickHouse. Configure el TLS del ingress por separado de los ajustes 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 MCP HTTP/SSE.

Ejemplos de configuración

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)

Para solo 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)
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:4200,localhost:4200,mcp.example.com:4200  # Include every Host value clients and proxies send

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!
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

Cuando se usa transporte HTTP, el servidor se ejecutará en el puerto configurado (8000 por defecto). Por ejemplo, con la configuración anterior:

• Endpoint MCP: http://localhost:8000/mcp

• Comprobación de salud: http://localhost:8000/health

Puede establecer estas variables en su 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: Los ajustes de host y puerto de enlace solo se usan cuando el transporte está configurado como "http" o "sse".

Ejecutar las 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

Descripción general de YouTube