ClickHouse

oficial

Consulta tu servidor de base de datos ClickHouse.

GitHub
902

¿Qué puedes hacer con ClickHouse MCP?

  • Ejecutar consultas SQL — Solicite ejecutar cualquier consulta SQL en su clúster de ClickHouse mediante run_query, con parámetros nombrados opcionales a través de params.
  • Listar bases de datos — Descubra todas las bases de datos disponibles en su clúster de ClickHouse usando list_databases.
  • Explorar tablas con filtros — Use list_tables para explorar tablas en una base de datos, aplicando patrones like/not_like y paginación mediante page_token y page_size.
  • Inspeccionar esquemas de consultas — Solicite DESCRIBE (<query>) o EXPLAIN ESTIMATE <query> a través de run_query para verificar las columnas de salida o las lecturas estimadas antes de ejecutar.
  • Consultar datos chDB integrados — Ejecute SQL directamente contra el motor integrado de chDB para consultar archivos, URLs o bases de datos sin ETL, usando run_chdb_select_query.

Documentación

Servidor MCP de ClickHouse

PyPI - Version

Un servidor MCP para ClickHouse.

mcp-clickhouse MCP server

El servidor implementa MCP 2026-07-28 y soporta 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 continuar 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 soportan 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 valores exactos en clientes JavaScript. Esto 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 placeholders de ClickHouse {name:Type}. Consulta Parámetros de consulta.
    • Las consultas se ejecutan en modo solo lectura por defecto (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), pero las escrituras pueden habilitarse 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 retiene hasta por una hora.
      • page_size (entero, predeterminado 50): Número de tablas devueltas por página; debe ser mayor que 0.
      • include_detailed_columns (booleano, predeterminado true): Cuando es false, omite metadatos de columnas para respuestas más ligeras mientras mantiene el create_table_query completo.
    • Forma de la respuesta:
      • tables: Arreglo 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 hay más tablas.
      • total_tables: Conteo total de tablas que coinciden con los filtros proporcionados.

Descubrimiento de esquema de Agents

Las instrucciones del servidor sugieren leer el Esquema de Agents canónico AGENTS.ROOT a través de run_query cuando list_databases revela una base de datos AGENTS, antes de escribir SQL analítico. Esto es orientación para el agente: no se obtienen metadatos automáticamente, los resultados de las herramientas no cambian, y los permisos existentes de ClickHouse siguen aplicándose. Si AGENTS.ROOT falta o es inaccesible, el descubrimiento normal y las consultas siguen disponibles.

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 placeholders de ClickHouse {name:Type} sin citarlos. Mantén la llave de apertura, el nombre y los dos puntos adyacentes, como en {id:UInt32}. Se soportan espacios después de los dos puntos y dentro del tipo, como en {id: UInt32} y {amount:Decimal(18, 4)}. Para compatibilidad entre versiones de controladores soportadas, 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 soportados. Las llamadas con solo query siguen funcionando. Omitir params, pasar null, o pasar un objeto vacío deja la consulta sin enlazar.

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

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

Los valores faltantes y los tipos incompatibles devuelven errores de consulta. Con params no vacío, una consulta con muchos inicios de placeholder {name: sin terminar es rechazada, incluyendo texto similar a placeholders 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 los 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 del 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 el número 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 una SELECT que podría ser costosa.

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, así 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 limpiamente aún puede fallar al ejecutarse, 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 por 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 de las dos declaraciones 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 embebido 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. Una falla o una recuperación pueden por lo tanto reportarse hasta un segundo tarde

Las solicitudes GET y HEAD al endpoint están intencionalmente sin autenticación y 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 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 errores; 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

Cuando se usa 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 soportan tres modos de autenticación. Elige uno:

ModoCuándo usarloVariable de entorno
Token estático de portadorImplementaciones simples, servicios internosCLICKHOUSE_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)
DeshabilitadoSolo desarrollo localCLICKHOUSE_MCP_AUTH_DISABLED=true

El inicio falla si ninguno de estos está configurado para 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 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 está intencionalmente sin autenticación (consulta Endpoint de verificación de salud arriba). Para verificar que la autenticación de token de portador realmente rechaza solicitudes sin autenticar, golpea el propio endpoint MCP, 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 sin autenticar 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 establecer.

Ejemplo (Azure Entra):

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"
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 proveedorPrefijo de variable del proveedor
fastmcp.server.auth.providers.auth0.Auth0ProviderFASTMCP_SERVER_AUTH_AUTH0_
fastmcp.server.auth.providers.aws.AWSCognitoProviderFASTMCP_SERVER_AUTH_AWS_COGNITO_
fastmcp.server.auth.providers.azure.AzureProviderFASTMCP_SERVER_AUTH_AZURE_
fastmcp.server.auth.providers.descope.DescopeProviderFASTMCP_SERVER_AUTH_DESCOPEPROVIDER_
fastmcp.server.auth.providers.discord.DiscordProviderFASTMCP_SERVER_AUTH_DISCORD_
fastmcp.server.auth.providers.github.GitHubProviderFASTMCP_SERVER_AUTH_GITHUB_
fastmcp.server.auth.providers.google.GoogleProviderFASTMCP_SERVER_AUTH_GOOGLE_
fastmcp.server.auth.providers.introspection.IntrospectionTokenVerifierFASTMCP_SERVER_AUTH_INTROSPECTION_
fastmcp.server.auth.providers.jwt.JWTVerifierFASTMCP_SERVER_AUTH_JWT_
fastmcp.server.auth.providers.oci.OCIProviderFASTMCP_SERVER_AUTH_OCI_
fastmcp.server.auth.providers.scalekit.ScalekitProviderFASTMCP_SERVER_AUTH_SCALEKITPROVIDER_
fastmcp.server.auth.providers.supabase.SupabaseProviderFASTMCP_SERVER_AUTH_SUPABASE_
fastmcp.server.auth.providers.workos.WorkOSProviderFASTMCP_SERVER_AUTH_WORKOS_
fastmcp.server.auth.providers.workos.AuthKitProviderFASTMCP_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 no recibe 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 confiable. Cualquiera 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. Cualquiera 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 proxy de cliente OAuth predeterminado. Las implementaciones que dependían del almacenamiento de proxy OAuth predeterminado de FastMCP 2 deben hacer que los clientes se registren y autoricen nuevamente. El almacenamiento personalizado compatible, los tokens de portador estáticos y la verificación JWT no se ven afectados.

Modo de Desarrollo (Deshabilitando 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 hasta 3.14. Se recomienda Python 3.12 para lanzamientos locales.

  1. 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

  2. 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"
      }
    }
  }
}

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

  2. Reinicie Claude Desktop para aplicar los cambios.

Acceso de Escritura Opcional

De forma predeterminada, este MCP aplica consultas de solo lectura para que no ocurran 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 instancia de ClickHouse en sí no permite escrituras.

El modo de solo lectura aún permite que el usuario de ClickHouse cancele sus propias consultas, incluidas las consultas de otras conexiones que usen el mismo usuario. Use un usuario de ClickHouse dedicado incluso en modo de solo lectura. Use usuarios de ClickHouse separados para cargas de trabajo que no deben cancelar las consultas entre sí.

Protección contra Operaciones Destructivas

Incluso cuando el acceso de escritura está habilitado (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), las operaciones destructivas requieren una marca 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 ni 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, otorgue 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;

Las operaciones que cambian datos y requieren privilegios fuera de estos permisos fallan en el lado del servidor con ACCESS_DENIED, independientemente de las marcas 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 ambas marcas:

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

  1. 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

  2. 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, prompts, etc.).

Cómo Usar

  1. 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())
  1. 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"
      }
    }
  }
}
  1. 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 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 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 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 enlace 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 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 de inquilinos 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 invá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 compatibles 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 secure selecciona la interfaz https o http correspondiente y no cambia el puerto. Una anulación explícita 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 confiable. 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 trabajo de base de datos bloqueante. 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 posteriores a herramientas 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

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

  2. 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

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

  2. Para probar fácilmente con el MCP Inspector, ejecuta uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp para iniciar el servidor MCP.

  3. 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

Estructura del código

El paquete utiliza una estructura de módulos plana. Comienza con mcp_server.py para el ensamblado y registro del servidor, luego sigue la implementación hasta su módulo propietario.

MóduloResponsabilidad
mcp_server.py, main.pyEnsamblado de inicio, registro de herramientas y prompts, coordinación de apagado e inicio CLI
clients.pyConfiguración de solicitudes, conexiones ClickHouse en caché y concesiones de clientes
queries.pyEjecución de consultas, cancelación y protecciones para operaciones destructivas
metadata.pyDescubrimiento de bases de datos y tablas, modelos de metadatos y paginación
chdb_backend.py, chdb_prompt.pyInicialización opcional de chDB, ejecución de consultas y contenido de prompts
health.py, executors.pySondas de salud y caché, y los grupos de trabajadores utilizados por las operaciones del servidor
auth.py, transport.py, http_security.pyCarga de dotenv, autenticación, construcción de la aplicación HTTP/SSE y validación de Host/Origin
mcp_env.py, serialization.pyConfiguración del entorno y codificación de resultados JSON
mcp_middleware_hook.py, skills_advisor.pyCarga de middleware personalizado e instrucciones del servidor

Cada ensamblado del servidor posee sus grupos de trabajadores, caché de clientes, consultas activas, caché de paginación, estado de salud y backend chDB. La limpieza de trabajadores y clientes se ejecuta al salir del proceso. Las importaciones del paquete inicializan el servidor predeterminado, incluso al importar por primera vez un módulo extraído.

En las pruebas, parchea el módulo o la instancia propietaria donde el código lee una dependencia. Por ejemplo, parchea mcp_clickhouse.clients.clickhouse_connect.get_client para la creación de clientes. Las importaciones de compatibilidad en mcp_server.py pueden ser enlaces separados de los que utiliza una implementación.

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:

GrupoVariablesControla
Conexión a la base de datos ClickHouseCLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, variables de certificadoCómo este servidor MCP se conecta a tu clúster ClickHouse a través de la interfaz HTTP
Servidor MCP / transporteCLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*, FASTMCP_ENV_FILETransporte MCP, autenticación y límites de ejecución de herramientas de consulta
Middleware / chDBMCP_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 HTTP/SSE entrante.

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 produzca 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 lo harías con cualquier cliente externo que se conecte a tu base de datos, otorgando solo los privilegios mínimos necesarios para su operación. 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 de 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: None
    • 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 se deshabilita 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 aún controla 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: None (usa 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 con 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: None
    • 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: None
    • 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: None, 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 entre mayúsculas y 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 la anulación de SNI y la validación de certificados en la conexión de ClickHouse
    • Predeterminado: None (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 de URL para el endpoint HTTP de ClickHouse
    • Predeterminado: None
    • 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: None (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 declaraciones destructivas además necesitan CLICKHOUSE_ALLOW_DROP=true
    • Cuando está deshabilitado (predeterminado), las consultas se ejecutan con la configuración 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 certificados 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, monte el certificado y la clave privada como archivos de solo lectura y use sus rutas dentro del contenedor. No incruste una clave privada en una imagen, no la confirme en el control de fuentes ni ponga 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. Configure la autenticación del transporte MCP por separado.

Reinicie 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 conservar conexiones TLS existentes, y la caché no rastrea contenidos de archivos ni tiempos de modificación.

ClickHouse Cloud no admite autenticación de certificado de cliente X.509 para usuarios de base de datos. Use CLICKHOUSE_USER y CLICKHOUSE_PASSWORD para ClickHouse Cloud. Un certificado de CA puede seguir siendo ú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 proceso MCP en sí, 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. Consulte también Autenticación para transportes HTTP/SSE.

  • CLICKHOUSE_MCP_SERVER_TRANSPORT: Establece el método de transporte para el servidor MCP
    • Predeterminado: "stdio"
    • Opciones válidas: "stdio", "http", "sse". Esto es útil para el desarrollo local con herramientas como MCP Inspector.
    • stdio es típico para Claude Desktop; http/sse exponen un listener de red (enlace de host/puerto a continuación)
    • "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 vincular el servidor MCP cuando se usa transporte HTTP o SSE
    • Predeterminado: "127.0.0.1"
    • Establézcalo en "0.0.0.0" para vincular 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 vincular 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 de herramientas de consulta
    • Predeterminado: "30"
    • Auméntelo si ve errores Query timed out after ... para consultas pesadas
    • Cuando una consulta agota el tiempo de espera, 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 de 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 distinción de 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 de checkout de 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)
    • Establézcalo 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 encabezado Host separados por comas a los que responde el servidor HTTP/SSE
    • 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 rebinding 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 de orquestadores 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 la desactivación de la protección separada de Host y Origen de FastMCP. 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-* se confían
    • 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 de socket bruto inmediato. 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 suministrados 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 bruto y 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 aserció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 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 deshabilitada la confianza de Host reenviado:

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 de 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 de 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"
    • Establecer 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
    • Predeterminado: ":memory:" (base de datos en memoria)
    • Usar :memory: para base de datos en memoria
    • Usar 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 un ingress de Kubernetes, un proxy inverso, o se accede a través de HTTP simple no desactiva 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 la configuración del cliente de base de datos.
  • Puertos del protocolo nativo — CLICKHOUSE_PORT debe apuntar a la interfaz HTTP de ClickHouse (8123/8443 por defecto). Los puertos 9000/9440 son para el protocolo TCP nativo (clickhouse-client) y no funcionarán con este servidor.
  • Confusión de host — CLICKHOUSE_HOST es el nombre de host de la base de datos. CLICKHOUSE_MCP_BIND_HOST es solo la dirección en la que escucha el servidor HTTP/SSE de MCP.

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 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 use autenticación Básica.

Para chDB solo (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 (8000 por defecto). Por ejemplo, con la configuración anterior:

  • Endpoint de 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 de host y puerto de enlace solo se usa cuando el transporte está establecido en "http" o "sse".

Ejecutar pruebas

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

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

Resumen de YouTube

YouTube