mcp-clickhouse

mcp-clickhouse

Um servidor Model Context Protocol para ClickHouse. Ele permite que um cliente compatível com MCP (Claude Desktop, Claude Code, etc.) explore esquemas, execute consultas analíticas e gerencie o banco de dados — com o comportamento controlado inteiramente por flags.

O modelo de segurança é ciente de declarações: cada instrução SQL é classificada como leitura, escrita ou destrutiva, e controlada pelo modo de acesso atual. O modo somente leitura adicionalmente executa consultas sob a própria configuração readonly=1 do ClickHouse.

Recursos

• Exploração e monitoramento — bancos de dados, tabelas, colunas, SHOW CREATE, estatísticas de tabelas (partes/linhas/bytes), consultas em execução, métricas do servidor, topologia do cluster.
• Consultas de leitura — uma ferramenta query que aceita apenas declarações de leitura, limitada a CLICKHOUSE_MAX_ROWS.
• Gerenciamento — uma ferramenta execute para INSERT/CREATE/ALTER (leitura-escrita) e DROP/TRUNCATE/DELETE (admin), cada uma controlada por classificação.
• Modos de acesso — read-only → read-write → admin, em camadas para que um modo nunca exponha declarações acima do seu nível.
• Flags de segurança — lista de permissão de bancos de dados, bancos de dados protegidos, controle de operações destrutivas, limite de linhas, simulação (dry-run) e registro de auditoria em JSON (veja abaixo).

Modelo de segurança

Preocupação	Flag	Padrão	Efeito
O que o servidor pode fazer?	CLICKHOUSE_MODE	read-only	read-only expõe apenas ferramentas de leitura (e recusa não-SELECT em query); read-write adiciona execute para escritas; admin permite declarações destrutivas.
Quais bancos de dados estão no escopo?	CLICKHOUSE_DATABASE_ALLOWLIST	(todos)	Quando definido, operações em outros bancos de dados são recusadas.
Quais bancos de dados são somente leitura para sempre?	CLICKHOUSE_PROTECTED_DATABASES	system,information_schema	Legíveis, nunca mutáveis.
Pode executar SQL destrutivo?	CLICKHOUSE_ALLOW_DELETE	false	DROP/TRUNCATE/DELETE/… precisam disso e do modo admin.
Limite de tamanho do resultado	CLICKHOUSE_MAX_ROWS	1000	Limite rígido de linhas retornadas ao modelo.
Pré-visualização sem executar	CLICKHOUSE_DRY_RUN	false	Declarações de escrita/destrutivas validam + registram a intenção e retornam.
Trilha de auditoria	CLICKHOUSE_AUDIT_LOG	true	Emite uma linha JSON para stderr por operação protegida.

A classificação de declarações vive em src/sql.ts e é à prova de falhas: ALTER … DELETE/UPDATE conta como destrutivo, e qualquer coisa não analisável é tratada como destrutiva.

Ferramentas

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

Escrita/Admin (read-write+): execute — executa uma única declaração após classificá-la; escritas precisam do modo leitura-escrita, declarações destrutivas precisam do modo admin + CLICKHOUSE_ALLOW_DELETE.

Início rápido — adicione ao seu agente

Publicado no npm como @dockndevai/mcp-clickhouse. Sem necessidade de clone ou build — seu cliente MCP o executa sob demanda com npx. Comece no modo read-only; veja .env.example para cada variável e docs/CLIENTS.md para o guia completo 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 — mesmo bloco em claude_desktop_config.json, .cursor/mcp.json ou ~/.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 — em ~/.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) — em .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"
      }
    }
  }
}

Exemplos de prompts

• "Quais são as maiores tabelas no banco de dados analytics?"
• "Mostre-me o esquema de events e execute uma consulta para contagens diárias desta semana."
• "Quais consultas estão em execução agora e usando mais memória?"

Executar a partir do código-fonte (desenvolvimento)

Prefira o pacote publicado acima. Para executar a partir de um clone:

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

Desenvolvimento

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

Publicação

Este servidor inclui um server.json para o registro oficial do MCP e um mcpName para validação de propriedade no npm. Veja PUBLISHING.md para publicar no npm e listar no registro MCP, Smithery, Glama, Cursor e PulseMCP.

Licença

MIT