ClickHouse

oficial

Consulta tu servidor de base de datos ClickHouse.

GitHub

877

¿Qué puedes hacer con ClickHouse MCP?

Ejecutar consultas SQL — Solicita ejecutar cualquier consulta SQL en tu clúster de ClickHouse mediante run_query, con parámetros nombrados opcionales.
Listar bases de datos — Solicita ver todas las bases de datos disponibles en tu clúster de ClickHouse usando list_databases.
Explorar tablas con filtros — Solicita listar tablas en una base de datos con patrones LIKE/NOT LIKE y paginación mediante list_tables.
Inspeccionar el esquema de consultas — Solicita verificar las columnas y tipos de salida de una consulta antes de ejecutarla usando DESCRIBE.
Estimar el costo de la consulta — Solicita previsualizar las lecturas estimadas (partes, filas, marcas) para un SELECT usando EXPLAIN ESTIMATE.

Documentación

Servidor MCP de ClickHouse

Un servidor MCP para ClickHouse.

El servidor implementa MCP 2026-07-28 y admite handshakes de inicialización heredados desde 2024-11-05 hasta 2025-11-25. Los clientes modernos usan solicitudes sin sesión y server/discover. Los clientes existentes pueden seguir negociando el protocolo heredado.

[!NOTE] Las solicitudes HTTP sin MCP-Protocol-Version se enrutan a través del manejo heredado para que los clientes anteriores a 2025-06-18 puedan seguir conectándose. MCP 2026-07-28 permite este comportamiento en servidores que admiten esos clientes. Los clientes modernos deben enviar el encabezado en cada solicitud POST.

Características

Herramientas de ClickHouse

Las respuestas de las herramientas de ClickHouse son cadenas codificadas en JSON. Los enteros fuera de [-9007199254740991, 9007199254740991] se devuelven como cadenas decimales para preservar los valores exactos en clientes JavaScript. Esto se aplica a filas de consultas y metadatos de tablas enteras. Los enteros dentro del rango seguro y los booleanos mantienen sus tipos JSON.

run_query
- Ejecuta consultas SQL en tu clúster de ClickHouse.
- Entrada: query (cadena): La consulta SQL a ejecutar.
- Entrada opcional: params (objeto): Valores nombrados para los marcadores de posición {name:Type} de ClickHouse. Consulta Parámetros de consulta.
- Las consultas se ejecutan en modo de solo lectura por defecto (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), pero las escrituras se pueden habilitar explícitamente si es necesario.
- DESCRIBE (<query>) y EXPLAIN ESTIMATE <query> también se ejecutan aquí y son formas opcionales de inspeccionar el esquema de resultados de una consulta o sus lecturas estimadas. Consulta Verificar una consulta antes de ejecutarla.
list_databases
- Lista todas las bases de datos en tu clúster de ClickHouse.
list_tables
- Lista tablas en una base de datos con paginación.
- Entrada requerida: database (cadena).
- Entradas opcionales:
  - like / not_like (cadena): Aplica filtros LIKE o NOT LIKE a los nombres de tablas.
  - page_token (cadena): Token de un solo uso devuelto por una llamada anterior. Se conserva hasta por una hora.
  - page_size (entero, por defecto 50): Número de tablas devueltas por página; debe ser mayor que 0.
  - include_detailed_columns (booleano, por defecto true): Cuando es false, omite los metadatos de columnas para respuestas más ligeras mientras mantiene el create_table_query completo.
- Forma de la respuesta:
  - tables: Matriz de objetos de tabla para la página actual.
  - next_page_token: Pasa este valor de un solo uso de vuelta antes de que expire para obtener la siguiente página, o null cuando no haya más tablas.
  - total_tables: Conteo total de tablas que coinciden con los filtros proporcionados.

Parámetros de consulta

Pasa valores por separado del SQL a través del objeto opcional params:

{
  "query": "SELECT {id:UInt32} AS id, {name:String} AS name",
  "params": {"id": 13, "name": "O'Reilly"}
}

Usa los marcadores de posición {name:Type} de ClickHouse sin citarlos. Mantén la llave de apertura, el nombre y los dos puntos adyacentes, como en {id:UInt32}. Los espacios después de los dos puntos y dentro del tipo son compatibles, como en {id: UInt32} y {amount:Decimal(18, 4)}. Para compatibilidad entre versiones de controladores compatibles, comienza los nombres con una letra o guion bajo y usa solo letras, dígitos y guiones bajos. El formato estilo Python %s o %(name)s y los parámetros binarios crudos $name$ del controlador no son compatibles. Las llamadas con solo query aún funcionan. Omitir params, pasar null o pasar un objeto vacío deja la consulta sin enlazar.

Los valores de parámetros pueden ser cadenas JSON, números, booleanos, null o matrices, siempre que coincidan con el tipo de ClickHouse declarado:

Usa null con un tipo Nullable(...).
Pasa enteros exactos fuera del rango seguro de JavaScript como cadenas decimales, por ejemplo "18446744073709551615" con {id:UInt64}. Las fechas, marcas de tiempo y decimales exactos también se pueden pasar como cadenas con el tipo de ClickHouse correspondiente.
Vincula vectores como una sola matriz, por ejemplo {vector:Array(Float32)} con "params": {"vector": [0.25, 0.5, 0.75]}.
Los nulos dentro de matrices dependen del controlador instalado. Funcionan con clickhouse-connect 1.8.0 pero fallan con el mínimo compatible 1.0.0.
Las listas y objetos JSON no se pueden vincular a los tipos Tuple y Map de ClickHouse.

Los valores faltantes y los tipos incompatibles devuelven errores de consulta. Con params no vacío, se rechaza una consulta que lleva muchos inicios de marcadores de posición {name: sin terminar, incluido texto similar a marcadores de posición en comentarios o literales de cadena. Las consultas parametrizadas usan la misma protección de escritura, tiempos de espera, cancelación y codificación de resultados JSON que otras consultas.

Los valores de parámetros se mantienen fuera de los mensajes de registro SQL normales del servidor MCP, pero permanecen en los argumentos de las herramientas MCP y pueden aparecer en errores de backend. ClickHouse 26.3.20.7 sustituye valores en el texto de la consulta en system.query_log, system.processes y system.text_log. El enlace de parámetros no es una característica de privacidad y no reduce la cantidad de valores vectoriales enviados en una llamada de herramienta.

Verificar una consulta antes de ejecutarla

run_query también ejecuta DESCRIBE y EXPLAIN ESTIMATE. Ambas son verificaciones opcionales: recurre a DESCRIBE cuando necesites las columnas y tipos de salida de una consulta, y a EXPLAIN ESTIMATE antes de un SELECT que podría ser costoso.

DESCRIBE (<query>) inspecciona el esquema de resultados y devuelve los mismos metadatos de columnas de salida que DESCRIBE TABLE:

DESCRIBE (SELECT user, sum(amt) FROM events WHERE ts > now() - INTERVAL 30 DAY GROUP BY user)

user      String
sum(amt)  Decimal(38, 2)

ClickHouse tiene que analizar la consulta para responder, por lo que los errores de análisis aparecen aquí, con el mensaje propio de ClickHouse, en lugar de a mitad de la ejecución:

DESCRIBE (SELECT usr FROM events)  -> Code: 47. Unknown expression identifier `usr` ... Maybe you meant: ['user']
DESCRIBE (SELECT * FROM nosuch)    -> Code: 60. Unknown table expression identifier 'nosuch'

Una consulta que se describe correctamente aún puede fallar cuando se ejecuta, por un límite de memoria o un error del servidor remoto, y no dice nada sobre el costo.

EXPLAIN ESTIMATE <query> devuelve las partes, filas y marcas que la consulta leería, una fila por tabla, que es lo que distingue una búsqueda por clave primaria de un escaneo completo:

EXPLAIN ESTIMATE SELECT count() FROM events WHERE id = 42

database  table   parts  rows   marks
default   events  1      8192   1

Esas son lecturas estimadas de tablas de la familia MergeTree, después de la poda de clave primaria y partición. No son tiempo de ejecución ni tamaño de resultado, y otros motores de tabla no están cubiertos.

Ninguna declaración ejecuta el cuerpo de la consulta, pero el análisis no siempre es gratuito: DESCRIBE (SELECT (SELECT sleep(1))) ejecuta la subconsulta escalar mientras analiza. Ambas son de solo lectura y funcionan bajo el CLICKHOUSE_ALLOW_WRITE_ACCESS=false predeterminado. Consulta la documentación de ClickHouse para EXPLAIN ESTIMATE y DESCRIBE.

Herramientas de chDB

run_chdb_select_query
- Ejecuta consultas SQL usando el motor ClickHouse integrado de chDB.
- Entrada: query (cadena): La consulta SQL a ejecutar.
- Los enteros fuera de [-9007199254740991, 9007199254740991] se devuelven como cadenas decimales.
- 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á 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
Devuelve 503 si una sonda de ClickHouse no termina dentro de dos segundos. Las solicitudes concurrentes comparten una sonda en vuelo
Reutiliza un resultado de sonda completado durante un segundo, por lo que las sondas que llegan en sucesión rápida no se conectan cada una a ClickHouse. Por lo tanto, una falla o una recuperación se puede informar hasta con un segundo de retraso

Las solicitudes GET y HEAD al endpoint son intencionalmente no autenticadas y están exentas de la validación de Host y Origin para que las sondas de orquestadores (por ejemplo, liveness/readiness de Kubernetes, balanceadores de carga) puedan usar IPs de pod o destino asignadas en tiempo de ejecución sin configuración adicional. /health está reservado y no se puede usar como ruta de transporte MCP. El cuerpo de la respuesta es deliberadamente mínimo para evitar filtrar cadenas de versión de backend o detalles de error; depura fallas a través de los registros 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 (predeterminado) no requiere autenticación ya que solo se comunica a través de entrada/salida estándar.

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

Modo	Cuándo usarlo	Variable de entorno
Token estático de portador	Implementaciones 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 ninguno de estos está configurado para transportes HTTP/SSE.

Configuración de la autenticación

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

# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

Configura el servidor con el token:

export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

Configura tu cliente MCP para incluir el token en las solicitudes:

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 es intencionalmente no autenticado (consulta Endpoint de verificación de salud arriba). Para verificar que la autenticación de token de portador realmente rechaza solicitudes no autenticadas, golpea el endpoint MCP mismo, por ejemplo con el Inspector MCP, o enviando una solicitud JSON-RPC a /mcp con y sin el encabezado Authorization y confirmando que la llamada no autenticada devuelve 401.

OAuth / OIDC vía FastMCP

Para implementaciones de 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 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 configurar.

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>"
export FASTMCP_SERVER_AUTH_AZURE_BASE_URL="https://mcp.example.com"
export FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES="read access_as_user"

mcp-clickhouse conserva estos prefijos de entorno de FastMCP 2.14.7 para los proveedores integrados de FastMCP 4.0.0:

Ruta de clase del proveedor	Prefijo de variable del proveedor
`fastmcp.server.auth.providers.auth0.Auth0Provider`	`FASTMCP_SERVER_AUTH_AUTH0_`
`fastmcp.server.auth.providers.aws.AWSCognitoProvider`	`FASTMCP_SERVER_AUTH_AWS_COGNITO_`
`fastmcp.server.auth.providers.azure.AzureProvider`	`FASTMCP_SERVER_AUTH_AZURE_`
`fastmcp.server.auth.providers.descope.DescopeProvider`	`FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_`
`fastmcp.server.auth.providers.discord.DiscordProvider`	`FASTMCP_SERVER_AUTH_DISCORD_`
`fastmcp.server.auth.providers.github.GitHubProvider`	`FASTMCP_SERVER_AUTH_GITHUB_`
`fastmcp.server.auth.providers.google.GoogleProvider`	`FASTMCP_SERVER_AUTH_GOOGLE_`
`fastmcp.server.auth.providers.introspection.IntrospectionTokenVerifier`	`FASTMCP_SERVER_AUTH_INTROSPECTION_`
`fastmcp.server.auth.providers.jwt.JWTVerifier`	`FASTMCP_SERVER_AUTH_JWT_`
`fastmcp.server.auth.providers.oci.OCIProvider`	`FASTMCP_SERVER_AUTH_OCI_`
`fastmcp.server.auth.providers.scalekit.ScalekitProvider`	`FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_`
`fastmcp.server.auth.providers.supabase.SupabaseProvider`	`FASTMCP_SERVER_AUTH_SUPABASE_`
`fastmcp.server.auth.providers.workos.WorkOSProvider`	`FASTMCP_SERVER_AUTH_WORKOS_`
`fastmcp.server.auth.providers.workos.AuthKitProvider`	`FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_`

Agrega el nombre del campo del proveedor en mayúsculas al prefijo. Consulta la documentación de FastMCP para los requisitos de configuración de cada proveedor. Los valores de autenticación establecidos directamente en el entorno del proceso tienen prioridad sin distinguir entre mayúsculas y minúsculas. La carga predeterminada de .env comienza en el directorio del paquete instalado de mcp_clickhouse, resuelve primero los enlaces simbólicos y asciende hasta la raíz del sistema de archivos. Carga el primer .env que encuentre y no carga nada si no hay ninguno. Nunca lee el directorio de trabajo, independientemente de cómo se inicie el servidor. Una copia del código fuente normalmente encuentra el .env de la raíz del repositorio. Ese archivo también puede proporcionar FASTMCP_SERVER_AUTH y sus campos de proveedor. Sus valores tienen prioridad sobre el archivo de autenticación explícito o de compatibilidad. Para la compatibilidad con FastMCP 2, mcp-clickhouse lee los campos de proveedor faltantes de .env en el directorio de trabajo, pero esa alternativa de compatibilidad no puede seleccionar FASTMCP_SERVER_AUTH. Un FASTMCP_ENV_FILE establecido en el proceso reemplaza esa alternativa de compatibilidad y puede proporcionar tanto el selector como los campos de proveedor. Establézcalo antes del inicio. El cargador de compatibilidad de mcp-clickhouse solo lee FASTMCP_SERVER_AUTH y FASTMCP_SERVER_AUTH_* de ese archivo, por lo que no puede inyectar configuraciones de CLICKHOUSE_*. FastMCP 4 puede usar el mismo archivo para sus propias configuraciones más amplias. Un proveedor personalizado recibe sin argumentos de constructor derivados del entorno y debe admitir la construcción sin argumentos.

Trate tanto los archivos .env descubiertos como los del directorio de trabajo como configuración de autenticación de confianza. Cualquier persona que pueda crear o escribir un .env en cualquier directorio desde el directorio del paquete hasta la raíz del sistema de archivos puede controlar qué archivo se descubre, seleccionar el proveedor y establecer sus campos. Cualquier persona que pueda escribir el archivo del directorio de trabajo controla cada campo de proveedor ausente del proceso y de la configuración descubierta, incluidas las claves de firma, emisores y endpoints, y secretos de cliente. Un FASTMCP_ENV_FILE establecido en el proceso que apunte a un archivo propiedad del operador deshabilita la alternativa del directorio de trabajo.

FastMCP 4 cambió el almacén de clientes proxy OAuth predeterminado. Las implementaciones que dependían del almacenamiento proxy OAuth predeterminado de FastMCP 2 deben hacer que los clientes se registren y autoricen nuevamente. El almacenamiento personalizado compatible, los tokens portadores estáticos y la verificación JWT no se ven afectados.

Modo de desarrollo (deshabilitación de la autenticación)

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

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

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

Configuración

Este servidor MCP admite tanto ClickHouse como chDB. Puede habilitar cualquiera o ambos según sus necesidades. Se admiten Python 3.10 a 3.14. Se recomienda Python 3.12 para lanzamientos locales.

Abra 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
Agregue lo siguiente:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "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"
      }
    }
  }
}

Actualice las variables de entorno para que apunten a su propio servicio de ClickHouse.

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

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "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"
      }
    }
  }
}

Para chDB (motor ClickHouse integrado), agregue la siguiente configuración:

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

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

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.12",
        "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",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Localice la entrada de comando para uv y reemplácela con la ruta absoluta al ejecutable de uv. Esto garantiza que se use la versión correcta de uv al iniciar el servidor. En una Mac, puede encontrar esta ruta usando which uv.
Reinicie Claude Desktop para aplicar los cambios.

Acceso de escritura opcional

De forma predeterminada, este MCP aplica consultas de solo lectura para que no puedan ocurrir mutaciones accidentales durante la exploración. Para permitir sentencias DDL o INSERT, establezca 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 de operaciones destructivas

Incluso cuando el acceso de escritura está habilitado (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), las operaciones destructivas requieren un indicador de aceptación adicional por seguridad. La verificació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, comentarios SQL y nombres de parámetros {name:Type} se ignoran, por lo que no activan la verificación ni ocultan una sentencia de ella.

Esta verificación se ejecuta en el servidor MCP y es una protección de buena fe 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 puerta de operaciones destructivas no se aplica en el servidor.

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

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

Cada sentencia fuera de estos permisos falla entonces en el lado del servidor con ACCESS_DENIED, independientemente de los indicadores de MCP. La configuración del servidor max_table_size_to_drop y max_partition_size_to_drop también puede limitar el radio de impacto si se fija con restricciones de configuración.

Para habilitar operaciones destructivas, establezca ambos indicadores:

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

Este enfoque de dos niveles hace que la eliminación accidental sea difícil:

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 adicionalmente CLICKHOUSE_ALLOW_DROP=true

Ejecución sin uv (usando Python del sistema)

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

Instale 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

Actualice su 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"
      }
    }
  }
}

Alternativamente, puede 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"
      }
    }
  }
}

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

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

Middleware personalizado

Puede agregar middleware personalizado al servidor MCP sin modificar el código fuente. FastMCP proporciona un sistema de middleware que le permite interceptar y procesar mensajes de protocolo MCP (llamadas a herramientas, lecturas de recursos, indicaciones, etc.).

Cómo usar

Cree 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())

Establezca 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.12", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}

Asegúrese de que su módulo de middleware esté en la ruta de importación de Python (por ejemplo, en el mismo directorio donde se ejecuta el servidor MCP, o instalado como paquete).

Ejemplo de middleware

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

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

Para usar el ejemplo:

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

Capacidades del middleware

La clase base Middleware proporciona enlaces 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 solicitudes
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 una indicación
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 indicaciones

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

Configuración dinámica del cliente mediante estado de contexto

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

from fastmcp.server.dependencies import get_context
from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY


class ClientConfigMiddleware(Middleware):
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        ctx = get_context()
        await ctx.set_state(
            CLIENT_CONFIG_OVERRIDES_KEY,
            {
                "connect_timeout": 60,
                "send_receive_timeout": 120,
            },
            serializable=False,
        )
        return await call_next(context)

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

El valor del estado debe ser un diccionario. Los valores anidados 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, más las mismas claves bajo generic_args, se rechazan.

Establezca verify, ca_cert, client_cert, client_cert_key, tls_mode, server_host_name, y pool_mgr solo como anulaciones de nivel superior. No pueden estar anidadas bajo generic_args. Un pool_mgr personalizado no se puede combinar con configuraciones de CA administrada o certificado de cliente. Los parámetros de consulta DSN no pueden establecer estas claves, y un DSN no puede seleccionar el backend chdb. Use anulaciones explícitas de nivel superior host, port, username, password, database y secure para cambiar la conexión. Un DSN reenviado no reemplaza los campos de conexión base poblados ni selecciona TLS. Puede completar campos vacíos y proporcionar parámetros de consulta admitidos como query_limit. Las anulaciones secure y verify aceptan booleanos o las cadenas true y false. verify también acepta proxy, que se comporta como tls_mode: proxy cuando tls_mode no está establecido y por lo tanto usa autenticación Basic con la contraseña del entorno. Una anulación de secure selecciona la interfaz https o http correspondiente y no cambia el puerto. Una anulación explícita de interface debe ser http o https y coincidir con secure. Después de fusionar las anulaciones, los modos de certificado de cliente predeterminado y mutual omiten la contraseña. Los modos proxy y strict usan autenticación Basic con la contraseña del entorno a menos que la anulación proporcione sus propias credenciales.

Trate estas anulaciones como entrada de middleware de confianza. El middleware debe autenticar y autorizar los valores derivados de la solicitud antes de establecerlos. Use serializable=False para que FastMCP mantenga el valor en el estado local de la solicitud. El serializable=True predeterminado almacena el estado de la sesión y es rechazado por el servidor. El servidor toma una instantánea del valor antes de despachar el trabajo de base de datos de bloqueo. No almacene datos de inquilinos en el estado de Contexto con ámbito de sesión. Una anulación rechazada con ámbito de sesión permanece adjunta a una sesión MCP heredada y hace que las llamadas a herramientas posteriores en esa sesión fallen hasta que el cliente se reconecte. Un rol de ClickHouse por solicitud es configuración de conexión, no un límite de autorización de inquilinos. Aplique el aislamiento de inquilinos con usuarios, roles y permisos de ClickHouse.

Desarrollo

En el directorio test-services ejecute docker compose up -d para iniciar el clúster de ClickHouse.
Agregue 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

Ejecute uv sync para instalar las dependencias. Para instalar uv siga las instrucciones aquí. Luego haga source .venv/bin/activate.
Para probar fácilmente con el Inspector de MCP, ejecute uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp para iniciar el servidor MCP.

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

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

[!IMPORTANT] CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, CLICKHOUSE_CA_CERT, CLICKHOUSE_CLIENT_CERT, CLICKHOUSE_CLIENT_CERT_KEY, CLICKHOUSE_TLS_MODE y CLICKHOUSE_PORT se aplican únicamente a la conexión saliente a la base de datos ClickHouse. No configuran TLS, certificados de cliente, puertos ni autenticación para el endpoint MCP entrante HTTP/SSE.

Ejemplo: si el servidor MCP se ejecuta en Kubernetes detrás de un ingress que termina TLS, eso es un asunto del transporte MCP. Mantén CLICKHOUSE_SECURE alineado con cómo el pod alcanza el propio ClickHouse (HTTPS → true, HTTP plano → 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 solo 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 respaldadas por ClickHouse, como run_query, list_databases y list_tables. mcp-clickhouse requiere clickhouse-connect 1.x, a partir de 1.0.0.

Variables obligatorias

CLICKHOUSE_HOST: El nombre de host de tu servidor ClickHouse (endpoint de 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
- Obligatoria a menos que CLICKHOUSE_CLIENT_CERT use el valor predeterminado o el modo TLS "mutual"
- En el modo predeterminado o "mutual", se utiliza la autenticación por certificado y no se envía la contraseña

[!CAUTION] Es importante tratar a tu usuario de base de datos MCP como tratarías a cualquier cliente externo que se conecte a tu base de datos, otorgando solo los privilegios mínimos necesarios para su funcionamiento. El uso de usuarios predeterminados o administrativos debe evitarse estrictamente 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 necesita configurarse a menos que se use un puerto no estándar
- Debe ser un puerto de interfaz HTTP, no el puerto del protocolo TCP nativo utilizado por clickhouse-client
- Valores comunes:
  - HTTP: 8123 (plano) / 8443 (TLS) — utilizado por este servidor y ClickHouse Cloud HTTPS
  - TCP nativo (no compatible aquí): 9000 (plano) / 9440 (TLS) — utilizado 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 el mapeo HTTP de tu implementación)
CLICKHOUSE_ROLE: El rol de ClickHouse a utilizar para la autenticación
- Predeterminado: Ninguno
- Establécelo si tu usuario requiere un rol específico
CLICKHOUSE_SECURE: Habilita HTTPS para la conexión a la base de datos ClickHouse (no para clientes MCP)
- Predeterminado: "true"
- Establécelo en "false" solo cuando el servidor MCP alcance ClickHouse por HTTP plano (típico para Docker Compose local en el puerto 8123)
- Deja "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 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 suele manifestarse como errores confusos del cliente HTTP en lugar de un mensaje claro de "esquema incorrecto"
CLICKHOUSE_VERIFY: Habilita/deshabilita la verificación de certificados SSL para la conexión HTTPS de ClickHouse
- Predeterminado: "true"
- Establécelo 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 tu sistema operativo mediante truststore.inject_into_ssl() al inicio. Se utiliza el manejo SSL predeterminado de Python si la inyección está deshabilitada con MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 o falla.
MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: Deshabilita la integración del almacén de confianza del sistema operativo a nivel de proceso para TLS
- Predeterminado: sin establecer (la integración del almacén de confianza está habilitada)
- Establécelo exactamente en "1" antes del inicio para omitir truststore.inject_into_ssl() y usar el manejo de certificados SSL predeterminado de Python. Otros valores no deshabilitan la integración.
- Esto no deshabilita la verificación de certificados. CLICKHOUSE_VERIFY sigue controlando la verificación para la conexión HTTPS de ClickHouse.
CLICKHOUSE_CA_CERT: Ruta a un paquete de certificados CA PEM para la conexión HTTPS de ClickHouse
- Predeterminado: Ninguno (utiliza el almacén de confianza del sistema operativo a menos que la inyección del almacén de confianza esté deshabilitada o falle)
- Úsalo solo cuando un servidor ClickHouse o un proxy privado presente un certificado firmado por una CA privada. Esto cambia la verificación del certificado del servidor y no habilita la autenticación por certificado de cliente.
- Requiere CLICKHOUSE_SECURE=true y CLICKHOUSE_VERIFY=true
CLICKHOUSE_CLIENT_CERT: Ruta a un certificado de cliente PEM para la conexión HTTPS de ClickHouse
- Predeterminado: Ninguno
- El archivo también puede contener la clave privada. De lo contrario, establece CLICKHOUSE_CLIENT_CERT_KEY.
- El usuario de ClickHouse aún proviene de CLICKHOUSE_USER.
CLICKHOUSE_CLIENT_CERT_KEY: Ruta a la clave privada PEM para CLICKHOUSE_CLIENT_CERT
- Predeterminado: Ninguno
- Opcional cuando la clave privada está incluida en el archivo de certificado de cliente
- No se puede usar sin CLICKHOUSE_CLIENT_CERT
CLICKHOUSE_TLS_MODE: Cómo usa clickhouse-connect CLICKHOUSE_CLIENT_CERT
- Predeterminado: Ninguno, que se comporta como "mutual" cuando se establece un certificado de cliente
- "mutual": Usa el certificado de cliente para la autenticación de usuario X.509 de ClickHouse. CLICKHOUSE_PASSWORD es opcional y no se envía.
- "proxy": Presenta el certificado de cliente a un proxy que termina TLS, luego usa la autenticación básica de ClickHouse. CLICKHOUSE_PASSWORD es obligatorio.
- "strict": Presenta el certificado de cliente porque el servidor ClickHouse requiere uno en la capa TLS, luego usa la autenticación básica de ClickHouse. CLICKHOUSE_PASSWORD es obligatorio. Este modo no refuerza la verificación del certificado del servidor. CLICKHOUSE_VERIFY controla esa verificación.
- clickhouse-connect trata "proxy" y "strict" de manera idéntica. Los dos nombres documentan la intención.
- Los valores se recortan y no distinguen mayúsculas de minúsculas. Un valor en blanco se trata como no establecido. Otros valores se rechazan antes de que se cree un cliente ClickHouse, en la primera llamada a una herramienta ClickHouse o en la sonda /health.
- Requiere CLICKHOUSE_CLIENT_CERT. Todas las opciones de certificado de cliente requieren CLICKHOUSE_SECURE=true.
CLICKHOUSE_SERVER_HOST_NAME: Nombre de host del servidor para anulación de SNI y validación de certificados 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 establece, este nombre de host se usará tanto para SNI (Indicación de Nombre de 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 endpoint HTTP de ClickHouse
- Predeterminado: Ninguno
- Establécelo 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: el menor entre 300 o CLICKHOUSE_MCP_QUERY_TIMEOUT + 5, para que los hilos de trabajo se desbloqueen poco después de un tiempo de espera de consulta
- Si se establece explícitamente, el valor se usa tal cual (por ejemplo, "300" para consultas de larga duración)
CLICKHOUSE_DATABASE: Base de datos ClickHouse predeterminada a utilizar
- Predeterminado: Ninguno (usa el valor predeterminado del servidor)
- Establécelo para conectarte automáticamente a una base de datos específica
CLICKHOUSE_ENABLED: Habilita/deshabilita las herramientas de base de datos ClickHouse
- Predeterminado: "true"
- Establécelo en "false" para deshabilitar las herramientas de ClickHouse cuando se usa solo chDB
CLICKHOUSE_ALLOW_WRITE_ACCESS: Permite operaciones de escritura (DDL y DML) contra ClickHouse
- Predeterminado: "false"
- Establécelo 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 (predeterminado), las consultas se ejecutan con el ajuste readonly=1 para evitar modificaciones de datos
CLICKHOUSE_ALLOW_DROP: Permite operaciones destructivas (cualquier DROP o TRUNCATE, DELETE y UPDATE incluidas las variantes ALTER TABLE, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION y DETACH ... PERMANENTLY)
- Predeterminado: "false"
- Solo tiene efecto cuando CLICKHOUSE_ALLOW_WRITE_ACCESS=true también está establecido
- Esta compuerta es una protección de accidentes de mejor esfuerzo en el servidor MCP, no un límite de seguridad. Restringe los permisos del usuario de ClickHouse para una aplicación real (consulta Protección de Operaciones Destructivas)

Archivos de certificado TLS de ClickHouse

Las variables de certificado contienen rutas de archivo, no contenidos PEM. mcp-clickhouse pasa estas rutas a clickhouse-connect. Para Docker o Kubernetes, monta el certificado y la clave privada como archivos de solo lectura y usa sus rutas dentro del contenedor. No incrustes una clave privada en una imagen, la confirmes en el control de fuentes ni pongas su contenido en una variable de entorno.

En el modo mutual, el certificado de cliente configurado identifica este proceso mcp-clickhouse como CLICKHOUSE_USER. No autentica clientes MCP entrantes ni pasa sus identidades a ClickHouse. Configura la autenticación del transporte MCP por separado.

Reinicia mcp-clickhouse después de reemplazar un certificado o clave en la misma ruta cuando se requiera rotación o revocación inmediata. Los clientes en caché pueden retener conexiones TLS existentes, y la caché no rastrea contenidos de archivos ni tiempos de modificación.

ClickHouse Cloud no admite autenticación por certificado de cliente X.509 para usuarios de base de datos. Usa CLICKHOUSE_USER y CLICKHOUSE_PASSWORD para ClickHouse Cloud. Un certificado CA aún puede ser útil cuando un proxy privado frente a un endpoint presenta un certificado firmado por una CA privada.

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 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 desarrollo local con herramientas como MCP Inspector.
- stdio es típico para Claude Desktop; http/sse exponen un listener de red (enlazar host/puerto abajo)
- "sse" selecciona el transporte HTTP+SSE independiente obsoleto y registra una advertencia. Use "http" para Streamable HTTP en nuevas implementaciones.
CLICKHOUSE_MCP_BIND_HOST: Host al que enlazar el servidor MCP cuando se usa transporte HTTP o SSE
- Predeterminado: "127.0.0.1"
- Establezca "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
- Predeterminado: "8000"
- Solo se usa cuando el transporte es "http" o "sse" — no está relacionado con CLICKHOUSE_PORT
CLICKHOUSE_MCP_QUERY_TIMEOUT: Tiempo de espera en segundos para llamadas a herramientas de consulta
- Predeterminado: "30"
- Auméntelo si ve errores Query timed out after ... para consultas pesadas
- Cuando una consulta agota el tiempo, el servidor intenta cancelarla con KILL QUERY
- A menos que CLICKHOUSE_SEND_RECEIVE_TIMEOUT se establezca explícitamente, el tiempo de espera de lectura HTTP está limitado a este valor más cinco segundos
CLICKHOUSE_MCP_MAX_WORKERS: Número máximo de hilos de trabajo de consulta concurrentes
- Predeterminado: "10"
- Auméntelo si su carga de trabajo requiere muchas llamadas a herramientas concurrentes
- Las herramientas de metadatos usan un grupo separado con min(4, CLICKHOUSE_MCP_MAX_WORKERS) hilos para que el descubrimiento de esquemas no pueda retrasar las consultas
CLICKHOUSE_MCP_AUTH_TOKEN: Token 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
- Genérelo usando uuidgen o openssl rand -hex 32
- Los clientes deben enviar este token en el encabezado Authorization: Bearer <token>
FASTMCP_SERVER_AUTH: Delegar autenticación a un proveedor de autenticación FastMCP
- Predeterminado: 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, mcp-clickhouse carga el proveedor desde las variables de entorno FASTMCP_SERVER_AUTH_* existentes; deje CLICKHOUSE_MCP_AUTH_TOKEN sin establecer en este modo
- Los proveedores personalizados no reciben argumentos de constructor derivados del entorno y deben admitir construcción sin argumentos
- FastMCP 4 ya no admite la verificación HS256 de Supabase. Las implementaciones de Supabase deben usar RS256 o ES256.
FASTMCP_ENV_FILE: Archivo opcional que contiene FASTMCP_SERVER_AUTH y variables de entorno específicas del proveedor
- Predeterminado: Ninguno. Cuando no se establece, el cargador de compatibilidad lee los campos de proveedor faltantes de .env en el directorio de trabajo. No lee FASTMCP_SERVER_AUTH de ese respaldo
- Establézcalo en el entorno del proceso antes del inicio. Un valor cargado desde el .env predeterminado no puede redirigir el cargador de compatibilidad
- Si se establece en el proceso, este archivo puede proporcionar tanto FASTMCP_SERVER_AUTH como campos de proveedor y reemplaza el respaldo del directorio de trabajo
- Los valores del entorno del proceso tienen prioridad sin distinguir mayúsculas y minúsculas
- El cargador de compatibilidad de mcp-clickhouse lee este archivo solo al construir la autenticación HTTP/SSE y lee solo las entradas FASTMCP_SERVER_AUTH y FASTMCP_SERVER_AUTH_*. FastMCP 4 puede leer el mismo archivo para su configuración más amplia
- La carga predeterminada de .env es separada. Comienza en el directorio del paquete mcp_clickhouse instalado, resuelve enlaces simbólicos, sube hasta la raíz del sistema de archivos y carga el primer .env encontrado o nada. Nunca lee el directorio de trabajo, independientemente del método de inicio. Ese archivo puede proporcionar FASTMCP_SERVER_AUTH y campos de proveedor junto con otras configuraciones del servidor. Una copia del código fuente normalmente encuentra el .env raíz del repositorio
CLICKHOUSE_MCP_AUTH_DISABLED: Deshabilitar autenticación para transportes HTTP/SSE
- Predeterminado: "false" (la autenticación está habilitada)
- Establezca "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 encabezado Host separados por comas a los que el servidor HTTP/SSE responde
- Predeterminado para un enlace de loopback: formas simples y de cualquier puerto de 127.0.0.1, localhost y [::1]
- Si se establece, el valor debe contener al menos una entrada de Host.
- Una dirección de enlace concreta no-loopback predeterminada a 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 reenlace de DNS. La validación de Origen a continuación es requerida por separado por MCP.
- 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:* coincide solo con valores que llevan un puerto. Un Host sin puerto (una implementación de puerto estándar donde el cliente omite :80/:443) debe listarse también como una entrada exacta simple (example.com).
- Las solicitudes con un encabezado 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 Origen para que las sondas del orquestador sigan funcionando.
- Detrás de un proxy inverso, prefiera preservar el encabezado Host original. Puede en su lugar listar el valor Host ascendente que envía el proxy. Establezca una lista explícita cuando un lanzador como fastmcp run anule la dirección de enlace para acceso remoto.
- mcp-clickhouse fuerza el guardián separado de Host y Origen de FastMCP a desactivado. FASTMCP_HTTP_HOST_ORIGIN_PROTECTION, FASTMCP_HTTP_ALLOWED_HOSTS y FASTMCP_HTTP_ALLOWED_ORIGINS no se aplican. CLICKHOUSE_MCP_ALLOWED_HOSTS y CLICKHOUSE_MCP_ALLOWED_ORIGINS son autoritativos.
CLICKHOUSE_MCP_TRUSTED_PROXIES: Direcciones IP de proxy o redes CIDR cuyos encabezados X-Forwarded-* son confiables
- Predeterminado: Ninguno. X-Forwarded-Host se ignora. El manejo existente de Uvicorn de X-Forwarded-For y X-Forwarded-Proto no cambia.
- Las entradas deben ser direcciones IP o redes CIDR, como 127.0.0.1,10.20.0.0/24,2001:db8::1. Los CIDR deben usar su dirección de red, por lo que 10.20.0.1/24 se rechaza. Nombres de host, direcciones IPv6 con ámbito, *, 0.0.0.0/0 y ::/0 también se rechazan.
- La confianza se basa en el par inmediato del socket sin procesar. Una solicitud de cualquier otro par, o una solicitud sin dirección de cliente, ignora X-Forwarded-Host y valida Host.
- Un par confiable puede enviar exactamente un encabezado X-Forwarded-Host que contenga un valor no vacío. Campos duplicados, valores vacíos y listas separadas por comas reciben 421 Misdirected Request. Si el encabezado está ausente, Host se valida.
- Use la dirección o red más estrecha posible. El servidor MCP solo debe ser alcanzable a través de proxies en los rangos configurados. Cada proxy confiable debe eliminar y sobrescribir los valores X-Forwarded-Host y X-Forwarded-Proto proporcionados por el cliente, y construir X-Forwarded-For desde el par de conexión verificado.
- El servidor integrado y fastmcp run deshabilitan el manejo externo de encabezados de proxy de Uvicorn, validan Host desde el par sin procesar, luego aplican X-Forwarded-For y X-Forwarded-Proto. Habilitar explícitamente uvicorn_config["proxy_headers"] falla el inicio en este modo.
- La incrustación directa de ASGI debe deshabilitar el manejo de encabezados de proxy en el servidor ASGI externo y llamar a mcp.http_app(raw_client_address_preserved=True). Sin esa afirmación explícita, la construcción de la aplicación falla cuando se configuran proxies confiables.
CLICKHOUSE_MCP_ALLOWED_ORIGINS: Valores de encabezado Origin separados por comas aceptados en HTTP/SSE
- Predeterminado: Ninguno, lo que rechaza cada solicitud que lleva un encabezado Origin
- MCP requiere validación de Origen para conexiones de transporte HTTP/SSE. Las solicitudes sin un Origen se aceptan porque los clientes MCP que no son navegadores normalmente lo omiten. Un Origen que no coincide recibe 403 Forbidden. El endpoint /health está exento como se describió anteriormente.
- Las entradas son exactas (http://localhost:3000) o aceptan cualquier puerto (http://localhost:*). Como con los hosts, la forma de cualquier puerto coincide solo con orígenes que llevan un puerto; un origen de puerto estándar (https://app.example.com) debe listarse exactamente.

Manejo de Host de proxy inverso

Preserve Host cuando sea posible. Esto mantiene la confianza de Host reenviado deshabilitada:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host "";
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Sanitice X-Forwarded-For y X-Forwarded-Proto independientemente de la confianza de X-Forwarded-Host. Uvicorn puede confiar en esos encabezados según el par del proxy incluso cuando CLICKHOUSE_MCP_TRUSTED_PROXIES no está establecido.

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

El nginx estándar cambia Host al nombre ascendente para solicitudes proxy. No crea ni sobrescribe X-Forwarded-Host. Si preservar Host no es posible, sobrescriba el encabezado reenviado en el borde confiable:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com
CLICKHOUSE_MCP_TRUSTED_PROXIES=10.20.0.8

La segunda configuración es segura solo cuando 10.20.0.8 es la dirección de origen inmediata del proxy, el puerto del servidor está aislado de otros clientes, y nginx sobrescribe los encabezados de reenvío entrantes como se muestra. Para una cadena de proxies, cada salto confiable debe descartar los valores entrantes no verificados antes de construir los nuevos encabezados de reenvío.

En un enlace IPv6 o de doble pila, los proxies IPv4 pueden aparecer como direcciones mapeadas IPv4 como ::ffff:10.20.0.8; estos se comparan automáticamente con entradas IPv4. El append_x_forwarded_host de Envoy agrega a un X-Forwarded-Host existente en lugar de sobrescribirlo, produciendo una lista separada por comas que se rechaza, así que configure el salto confiable para sobrescribir el encabezado en su lugar. En Kubernetes con NAT de origen (por ejemplo externalTrafficPolicy: Cluster) el par observado puede ser una IP de nodo en lugar del pod del proxy, así que confíe en el CIDR del pod o nodo según corresponda; ingress-nginx sobrescribe tanto Host como X-Forwarded-Host por sí mismo.

Variables de Middleware

MCP_MIDDLEWARE_MODULE: Nombre del módulo de Python que contiene middleware personalizado para inyectar en el servidor MCP
- Predeterminado: Ninguno (no se carga middleware)
- Establézcalo al 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 detalles y ejemplos

Variables de chDB

CHDB_ENABLED: Habilitar/deshabilitar la funcionalidad de chDB
- Predeterminado: "false"
- Establezca "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)
- Use :memory: para 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 vs TLS de MCP / ingress — Desactivar CLICKHOUSE_SECURE porque el servidor MCP está detrás de Kubernetes ingress, un proxy inverso, o se alcanza a través de HTTP simple no deshabilita el TLS de la base de datos; solo cambia cómo este proceso se conecta a ClickHouse. Configure el TLS de ingress 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 el servidor MCP HTTP/SSE escucha.

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)

Para una CA de servidor privada sin autenticación de certificado de cliente:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_VERIFY=true
CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem

Para autenticación de certificado de cliente X.509 de ClickHouse:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-certificate-user
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
# CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem  # Only for a private server CA
# CLICKHOUSE_TLS_MODE=mutual  # Optional. This is the default with a client certificate.

Para un certificado de cliente requerido por un servidor TLS estricto mientras ClickHouse usa autenticación Básica:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
CLICKHOUSE_TLS_MODE=strict

Use CLICKHOUSE_TLS_MODE=proxy en su lugar cuando un proxy de terminación TLS requiera el certificado del cliente y ClickHouse aún utilice autenticación Basic.

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

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

Endpoint MCP: http://localhost:8000/mcp
Verificació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.12",
        "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 del host de enlace y del puerto solo se utiliza cuando el transporte está establecido en "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