mcp-clickhouse

Un servidor de Model Context Protocol para ClickHouse. Permite que un cliente compatible con MCP (Claude Desktop, Claude Code, etc.) explore esquemas, ejecute consultas analíticas y administre la base de datos, con un comportamiento controlado enteramente por opciones.

El modelo de seguridad es sensible a las sentencias: cada sentencia SQL se clasifica como de lectura, escritura o destructiva, y se restringe según el modo de acceso actual. El modo de solo lectura, además, ejecuta las consultas bajo el propio ajuste readonly=1 de ClickHouse.

Características

• Exploración y monitorización — bases de datos, tablas, columnas, SHOW CREATE, estadísticas de tablas (partes/filas/bytes), consultas en ejecución, métricas del servidor, topología del clúster.

• Consultas de lectura — una herramienta query que solo acepta sentencias de lectura, limitada a CLICKHOUSE_MAX_ROWS.

• Gestión — una herramienta execute para INSERT/CREATE/ALTER (lectura-escritura) y DROP/TRUNCATE/DELETE (admin), cada una restringida por su clasificación.

• Modos de acceso — read-only → read-write → admin, en capas, de modo que nunca se exponen escrituras en analyze nos above its level.

• Opciones de seguridad — lista de bases de datos permitidas, bases de datos protegidas, control de destructivas, límite de filas, prueba previa sin ejecución y registro de auditoría JSON (ver más abajo).

Related MCP server: clickhouse-mcp-server

Modelo de seguridad

La clasificación de sentencias se encuentra en src/sql.ts y es de tipo fail-safe: ALTER … DELETE/UPDATE se considera destructiva, y cualquier sentencia no analizable se trata como destructiva.

Herramientas

Lectura (read-only+): list_databases, list_tables, describe_table, show_create_table, table_stats, running_queues, server_metrics, cluster_info, query

Escritura/Admin (read-write+): execute — ejecuta una sola sentencia tras clasificarla; las escrituras necesitan el modo read-write, y las destructivas el modo admin + CLICKHOUSE_ALLOW_DELETE.

Uso con tu cliente MCP

Funciona con Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code (Copilot) y cualquier otro cliente MCP — consulta docs/CLIENTS.md para la configuración de cada cliente.

Instalación

npm install
npm run build

Ejecutar con Claude Desktop / Claude Code

{
  "mcpServers": {
    "clickhouse": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-clickhouse/dist/index.js"],
      "env": {
        "CLICKHOUSE_URL": "http://clickhouse:8123",
        "CLICKHOUSE_USER": "readonly",
        "CLICKHOUSE_PASSWORD": "…",
        "CLICKHOUSE_MODE": "read-only",
        "CLICKHOUSE_DATABASE_ALLOWLIST": "analytics"
      }
    }
  }
}

Ejemplos de prompts

• "¿Cuáles son las tablas más grandes de la base de datos analytics?"

• "Muéstrame el esquema de events y ejecuta una consulta para ver los recuentos diarios de esta semana."

• "¿Qué consultas se están ejecutando ahora y usan más memoria?"

Desarrollo

npm run dev
npm test          # SQL classification + security policy (30 tests)
npm run typecheck

Publicación

Este servidor incluye un server.json para el, el registro oficial de MCP y un mcpName para la validación de propiedad en npm. Consulta PUBLISHING.md para publicar en npm y aparecer en el registro de MCP, así como en Smithery, Glama, Cursor y PulseMCP.

Licencia

MIT