Servidor MCP de ClickHouse

Un servidor MCP para ClickHouse.

Características

Herramientas

• run_select_query

  • Ejecute consultas SQL en su clúster ClickHouse.

  • Entrada: sql (cadena): la consulta SQL a ejecutar.

  • Todas las consultas de ClickHouse se ejecutan con readonly = 1 para garantizar que sean seguras.

• list_databases

  • Enumere todas las bases de datos en su clúster ClickHouse.

• list_tables

  • Enumerar todas las tablas de una base de datos.

  • Entrada: database (cadena): el nombre de la base de datos.

Configuración

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. Añade lo siguiente:

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

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

3. Localice la entrada de comando para uv y reemplácela con la ruta absoluta del ejecutable 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 .

4. Reinicie Claude Desktop para aplicar los cambios.

Desarrollo

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

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

Nota: El uso del usuario

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

4. Para realizar pruebas fácilmente, puede ejecutar mcp dev mcp_clickhouse/mcp_server.py para iniciar el servidor MCP.

Variables de entorno

Las siguientes variables de entorno se utilizan para configurar la conexión de ClickHouse:

Variables requeridas

• CLICKHOUSE_HOST : El nombre de host de su servidor ClickHouse

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

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

[!PRECAUCIÓN] Es importante tratar al usuario de la base de datos MCP como a cualquier cliente externo que se conecte a ella, otorgándole únicamente los privilegios mínimos necesarios para su funcionamiento. Se debe evitar estrictamente el uso de usuarios predeterminados o administrativos.

Variables opcionales

• CLICKHOUSE_PORT : El número de puerto de su servidor ClickHouse

  • Predeterminado: 8443 si HTTPS está habilitado, 8123 si está deshabilitado

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

• CLICKHOUSE_SECURE : Habilitar/deshabilitar la conexión HTTPS

  • Valor predeterminado: "true"

  • Establezca en "false" para conexiones no seguras

• CLICKHOUSE_VERIFY : Habilitar/deshabilitar la verificación del certificado SSL

  • Valor predeterminado: "true"

  • Establezca en "false" para deshabilitar la verificación del certificado (no recomendado para producción)

• CLICKHOUSE_CONNECT_TIMEOUT : Tiempo de espera de conexión en segundos

  • Valor predeterminado: "30"

  • Aumente este valor si experimenta tiempos de espera de conexión

• CLICKHOUSE_SEND_RECEIVE_TIMEOUT : Tiempo de espera de envío/recepción en segundos

  • Valor predeterminado: "300"

  • Aumente este valor para consultas de larga duración

• CLICKHOUSE_DATABASE : Base de datos predeterminada para utilizar

  • Predeterminado: Ninguno (usa el valor predeterminado del servidor)

  • Configure esto para conectarse automáticamente a una base de datos específica

Configuraciones de ejemplo

Para el desarrollo local con Docker:

Para ClickHouse Cloud:

Para ClickHouse SQL Playground:

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

Ejecución de pruebas

Descripción general de YouTube