ClickHouse MCP Server

ClickHouse MCP Server

Una implementación de servidor de Model Context Protocol (MCP) que permite a Claude AI interactuar con bases de datos ClickHouse a través de una interfaz segura y eficiente.

Requisitos previos

1. Node.js (versión 18 o superior)
2. Base de datos ClickHouse ejecutándose local o remotamente
3. Aplicación Claude Desktop instalada

Herramientas disponibles

1. clickhouse_query

   • Ejecutar consultas SELECT en tu clúster de ClickHouse
   • Entrada: sql (string): La consulta SQL a ejecutar
   • Nota: Solo se permiten consultas SELECT por razones de seguridad

2. clickhouse_show_tables

   • Listar todas las tablas en la base de datos de ClickHouse
   • No se requieren parámetros de entrada

3. clickhouse_describe_table

   • Describir el esquema de una tabla específica
   • Entrada: table (string): El nombre de la tabla a describir

Pasos de instalación

1. Instalar dependencias

npm install @modelcontextprotocol/sdk @clickhouse/client typescript @types/node

2. Compilar el TypeScript

npm run build

3. Crear el archivo del servidor

Copia el código principal del servidor en index.js y hazlo ejecutable:

chmod +x dist/index.js

4. Configurar Claude Desktop

1. Abre la aplicación Claude Desktop, ve a configuración, luego a Developer y haz clic en "Edit Configuration File"

2. O abre el archivo de configuración de Claude Desktop ubicado en:

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

3. Añade lo siguiente:

{
  "mcpServers": {
    "clickhouse": {
      "command": "node",
      "args": ["/path/to/your/clickhouse-mcp-server/dist/index.js"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

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

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

{
  "mcpServers": {
    "clickhouse": {
      "command": "node",
      "args": ["/path/to/your/clickhouse-mcp-server/dist/index.js"],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Importante: Actualiza la ruta en la configuración para que apunte a la ubicación real de tu archivo dist/index.js. Copia la ruta completa como se muestra en la imagen a continuación.

5. Probar el servidor

Antes de configurar Claude Desktop, prueba el servidor localmente:

node dist/index.js

El servidor debería iniciarse y mostrar "ClickHouse MCP server running on stdio".

7. Reiniciar Claude Desktop

Después de actualizar la configuración, reinicia Claude Desktop para que los cambios surtan efecto.

Ejemplo de uso

Después de la configuración, puedes pedirle a Claude que:

• "Muéstrame todas las tablas en la base de datos de ClickHouse"
• "Consulta la tabla user_events para los datos de hoy"
• "Describe el esquema de la tabla orders"

Desarrollo

Ejecutar pruebas

npm test

Compilar el proyecto

npm run build

Linting

npm run lint

Notas de seguridad

• El servidor solo permite consultas SELECT para la herramienta de consulta
• Considera configurar una autenticación adecuada para tu instancia de ClickHouse
• Usa variables de entorno para credenciales sensibles
• Restringe el acceso de red a tu servidor de ClickHouse según sea necesario

Solución de problemas

1. Problemas de conexión: Verifica que tu servidor de ClickHouse esté ejecutándose y sea accesible
2. Errores de permisos: Asegúrate de que el script de Node.js tenga los permisos de archivo adecuados
3. Problemas de configuración: Verifica que la ruta en la configuración de Claude Desktop apunte al archivo correcto
4. Dependencias: Asegúrate de que todos los paquetes npm estén instalados correctamente

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Ejemplo de uso

Después de la configuración, puedes pedirle a Claude que:

• "Muéstrame todas las tablas en la base de datos de ClickHouse"
• "Consulta la tabla user_events para los datos de hoy"

Notas de seguridad

• El servidor solo permite consultas SELECT para la herramienta de consulta
• Considera configurar una autenticación adecuada para tu instancia de ClickHouse
• Usa variables de entorno para credenciales sensibles
• Restringe el acceso de red a tu servidor de ClickHouse según sea necesario

Solución de problemas

1. Problemas de conexión: Verifica que tu servidor de ClickHouse esté ejecutándose y sea accesible
2. Errores de permisos: Asegúrate de que el script de Node.js tenga los permisos de archivo adecuados
3. Problemas de configuración: Verifica que la ruta en la configuración de Claude Desktop apunte al archivo correcto
4. Dependencias: Asegúrate de que todos los paquetes npm estén instalados correctamente