mcp-clickhouse

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 completamente por banderas.

El modelo de seguridad es consciente de declaraciones: cada declaración SQL se clasifica como lectura, escritura o destructiva, y se controla según el modo de acceso actual. El modo de solo lectura además ejecuta consultas bajo la propia configuración readonly=1 de ClickHouse.

Características

• Exploración y monitoreo: 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 declaraciones de lectura, limitada a CLICKHOUSE_MAX_ROWS.
• Administración: una herramienta execute para INSERT/CREATE/ALTER (lectura-escritura) y DROP/TRUNCATE/DELETE (administración), cada una controlada por clasificación.
• Modos de acceso: read-only → read-write → admin, en capas para que un modo nunca exponga declaraciones por encima de su nivel.
• Banderas de seguridad: lista blanca de bases de datos, bases de datos protegidas, control de destructivas, límite de filas, ejecución en seco y registro de auditoría JSON (ver más abajo).

Modelo de seguridad

Preocupación	Bandeera	Predeterminado	Efecto
¿Qué puede hacer el servidor?	CLICKHOUSE_MODE	read-only	read-only expone solo herramientas de lectura (y rechaza no-SELECT en query); read-write agrega execute para escrituras; admin permite declaraciones destructivas.
¿Qué bases de datos están en alcance?	CLICKHOUSE_DATABASE_ALLOWLIST	(todas)	Cuando se establece, se rechazan operaciones en otras bases de datos.
¿Qué bases de datos son de solo lectura para siempre?	CLICKHOUSE_PROTECTED_DATABASES	system,information_schema	Legibles, nunca mutables.
¿Puede ejecutar SQL destructivo?	CLICKHOUSE_ALLOW_DELETE	false	DROP/TRUNCATE/DELETE/… necesitan esto y modo administración.
Límite de tamaño de resultados	CLICKHOUSE_MAX_ROWS	1000	Límite estricto en filas devueltas al modelo.
Vista previa sin ejecutar	CLICKHOUSE_DRY_RUN	false	Las declaraciones de escritura/destructivas validan y registran la intención, luego regresan.
Rastro de auditoría	CLICKHOUSE_AUDIT_LOG	true	Emite una línea JSON a stderr por operación controlada.

La clasificación de declaraciones vive en src/sql.ts y es a prueba de fallos: ALTER … DELETE/UPDATE cuenta como destructivo, y cualquier cosa no analizable se trata como destructiva.

Herramientas

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

Escritura/Administración (read-write+): execute — ejecuta una sola declaración después de clasificarla; las escrituras necesitan modo lectura-escritura, las declaraciones destructivas necesitan modo administración + CLICKHOUSE_ALLOW_DELETE.

Inicio rápido: agrégalo a tu agente

Publicado en npm como @dockndevai/mcp-clickhouse. No se necesita clonar ni compilar: tu cliente MCP lo ejecuta bajo demanda con npx. Comienza en modo read-only; consulta .env.example para cada variable y docs/CLIENTS.md para la guía completa por cliente.

Claude Code (CLI)

claude mcp add clickhouse -e CLICKHOUSE_URL="http://localhost:8123" -e CLICKHOUSE_USER="default" -e CLICKHOUSE_MODE="read-only" -- npx -y @dockndevai/mcp-clickhouse

Claude Desktop · Cursor · Windsurf: el mismo bloque en claude_desktop_config.json, .cursor/mcp.json o ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "clickhouse": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_URL": "http://localhost:8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI: en ~/.codex/config.toml:

[mcp_servers.clickhouse]
command = "npx"
args = ["-y", "@dockndevai/mcp-clickhouse"]
env = { CLICKHOUSE_URL = "http://localhost:8123", CLICKHOUSE_USER = "default", CLICKHOUSE_MODE = "read-only" }

VS Code (GitHub Copilot, modo Agente): en .vscode/mcp.json:

{
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_URL": "http://localhost:8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_MODE": "read-only"
      }
    }
  }
}

Ejemplos de indicaciones

• "¿Cuáles son las tablas más grandes en la base de datos analytics?"
• "Muéstrame el esquema de events y ejecuta una consulta para los conteos diarios de esta semana."
• "¿Qué consultas se están ejecutando actualmente y usan más memoria?"

Ejecutar desde el código fuente (desarrollo)

Prefiere el paquete publicado anteriormente. Para ejecutar desde un clon:

npm install
npm run build
node dist/index.js   # with the environment variables set

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 registro oficial de MCP y un mcpName para la validación de propiedad de npm. Consulta PUBLISHING.md para publicar en npm y listar en el registro de MCP, Smithery, Glama, Cursor y PulseMCP.

Licencia

MIT