O que é ClickHouse MCP Server?
O ClickHouse MCP Server é o servidor de código aberto da ClickHouse para executar SQL em um cluster ClickHouse. Ele tem três ferramentas principais: run_query para SQL, list_databases e list_tables, com detalhes de schema paginados. run_query também aceita DESCRIBE e EXPLAIN ESTIMATE, para que um agente confira a saída e as leituras estimadas de uma consulta antes de executá-la, e desde a versão 0.7.0 (21 de setembro de 2026) aceita parâmetros de consulta nomeados. Uma ferramenta opcional de chDB executa SQL com o motor embutido da ClickHouse sobre arquivos e URLs.
Instale pelo PyPI (uvx mcp-clickhouse) e defina os dados de conexão, como CLICKHOUSE_HOST, no ambiente. Ele roda via stdio por padrão, ou via HTTP ou SSE, caso em que se recusa a iniciar sem um bearer token, um provedor OAuth ou OIDC, ou uma desativação explícita.
Clientes do ClickHouse Cloud têm uma segunda opção: um servidor remoto gerenciado em https://mcp.clickhouse.cloud/mcp com 13 ferramentas somente leitura, login por OAuth ou chave de API, ativado por serviço no console do Cloud. O repositório de código aberto tem cerca de 890 estrelas no GitHub e licença Apache 2.0.
Como instalar ClickHouse MCP Server
uvx mcp-clickhouseClickHouse MCP Server vale a pena?
Para trabalho analítico, um conjunto pequeno de ferramentas é uma vantagem. O agente lista bancos e tabelas, confere uma consulta com EXPLAIN ESTIMATE para ver quantas linhas e partes ela leria e então a executa. O modo somente leitura é o padrão e é imposto no próprio ClickHouse via readonly=1, e não pela análise do SQL; ativar gravações exige CLICKHOUSE_ALLOW_WRITE_ACCESS, e DROP, TRUNCATE, DELETE e UPDATE exigem ainda uma segunda flag, CLICKHOUSE_ALLOW_DROP.
O texto sobre segurança é incomumente completo. O modo HTTP se recusa a iniciar sem autenticação. O README alerta que um arquivo .env em qualquer diretório acima do pacote instalado pode alterar as configurações de autenticação, que usuários somente leitura ainda podem cancelar outras consultas executadas pelo mesmo usuário, e que o binding de parâmetros não é um recurso de privacidade, porque os valores ainda podem aparecer nos logs de consultas. Ele diz com clareza que a verificação de operações destrutivas protege contra acidentes e que os grants do ClickHouse são o verdadeiro limite.
A lacuna é o tamanho dos resultados. As consultas expiram após 30 segundos por padrão, mas uma issue aberta relata que um SELECT de 3 milhões de linhas devolveu 231 MiB dentro dessa janela, o suficiente para afogar o contexto de qualquer modelo. Até que um limite proposto seja incorporado, o hábito de usar LIMIT, uma configuração max_result_rows no usuário do banco ou um middleware resolvem.
A afirmação anterior de que a ClickHouse não oferece opção hospedada já não vale. O endpoint gerenciado do ClickHouse Cloud acrescenta ferramentas somente leitura para serviços, backups, ClickPipes e uma consulta de custos da organização de 31 dias, sem nada para instalar. O servidor de código aberto continua sendo o indicado para clusters autogerenciados, chDB ou equipes que querem acesso de gravação sob os próprios controles.
Onde ele se destaca
Um analista de produto em um e-commerce de 50 pessoas no ClickHouse Cloud
Responder perguntas pontuais sobre pedidos e funis sem escrever SQL
Conecte o Claude ao servidor somente leitura com um usuário dedicado do ClickHouse e deixe o agente listar tabelas e rodar EXPLAIN ESTIMATE antes de cada SELECT. O servidor é gratuito; as consultas são cobradas pela computação do serviço Cloud, a partir de cerca de US$ 0,39 por unidade-hora no Enterprise em AWS us-east-1.
Um engenheiro de plataforma de dados que roda ClickHouse autogerenciado no Kubernetes
Dar a vários agentes internos acesso compartilhado e autenticado ao data warehouse
Rode o mcp-clickhouse via HTTP com um provedor OIDC pelo FastMCP, mantenha as gravações desligadas e adicione um middleware que define configurações por tenant. O isolamento entre tenants ainda precisa vir dos usuários e papéis do ClickHouse.
Uma cientista de dados que trabalha com arquivos Parquet em um notebook
Consultar arquivos locais e remotos com SQL sem carregar um banco
Instale mcp-clickhouse[chdb] e ative run_chdb_select_query; o motor embutido lê arquivos e URLs diretamente. Sem servidor e sem conta do Cloud, mas as consultas chDB não têm proteção de gravação no lado do MCP além do que o motor permite.
Antes de decidir
- Configuração
- uvx mcp-clickhouse com CLICKHOUSE_HOST, CLICKHOUSE_USER e CLICKHOUSE_PASSWORD na configuração do cliente; documentado para o Claude Desktop e outros clientes stdio. Usuários do ClickHouse Cloud podem, em vez disso, ativar o MCP em um serviço e apontar um cliente para https://mcp.clickhouse.cloud/mcp.
- Integrações
- Três ferramentas (run_query, list_databases, list_tables) mais a opcional run_chdb_select_query. run_query é somente leitura, a menos que as gravações sejam ativadas; um middleware FastMCP pode interceptar chamadas para log ou configurações por usuário.
- Dados e privacidade
- O servidor pode ler tudo o que for concedido ao seu usuário do ClickHouse, então use um usuário dedicado com privilégio mínimo. Ele roda na sua máquina; nada vai para a empresa ClickHouse, a menos que o seu banco esteja no ClickHouse Cloud. Parâmetros de consulta podem aparecer nos logs de consultas do ClickHouse.
- Custo em escala
- O servidor é gratuito. No ClickHouse Cloud Enterprise, a computação custa de US$ 0,33 a US$ 0,52 por unidade-hora (8 GiB, 2 vCPU) e o armazenamento de US$ 22 a US$ 27,50 por TB-mês, conforme a região. Agentes que fazem varreduras sem EXPLAIN ESTIMATE podem acordar serviços ociosos e queimar computação.
- Limites
- Timeout padrão de consulta de 30 segundos e 10 threads de trabalho. Sem limite de linhas devolvidas (issue #223), sem ferramentas de administração e sem modo multiusuário embutido. A ferramenta de faturamento do servidor hospedado do Cloud cobre no máximo 31 dias por consulta.
O que é bom
- Somente leitura por padrão, imposto no servidor com readonly=1
- Ativação separada para DROP, TRUNCATE, DELETE e UPDATE
- EXPLAIN ESTIMATE permite que agentes confiram o custo antes de executar
- O modo HTTP exige um token ou OAuth/OIDC
O que não é
- Sem limite de tamanho de resultado; SELECTs grandes podem inundar o contexto
- Python e uv necessários para o servidor rodado por conta própria
- Sem isolamento multiusuário ou por tenant além dos grants do ClickHouse
- O servidor hospedado do Cloud é um produto separado e somente leitura
Ideal para
Equipes de dados que querem um agente para responder perguntas a partir do ClickHouse com padrões seguros.
Alternativas ao ClickHouse MCP Server
ClickHouse MCP Server: perguntas frequentes
- ClickHouse MCP Server vale a pena?
- Três ferramentas e o padrão somente leitura fazem deste um primeiro servidor de banco seguro para um agente de análise, desde que você mesmo limite o tamanho dos resultados. Damos nota 4.2 de 5.
- Quanto custa ClickHouse MCP Server?
- Gratuito e com licença Apache-2.0. O ClickHouse Cloud é cobrado à parte (computação Enterprise a partir de cerca de US$ 0,33 por unidade-hora de 8 GiB) e oferece um teste de 30 dias com US$ 300 em créditos.
- Quais são as desvantagens de ClickHouse MCP Server?
- Sem limite de tamanho de resultado; SELECTs grandes podem inundar o contexto; python e uv necessários para o servidor rodado por conta própria; sem isolamento multiusuário ou por tenant além dos grants do ClickHouse; o servidor hospedado do Cloud é um produto separado e somente leitura.
- Para quem ClickHouse MCP Server é indicado?
- Equipes de dados que querem um agente para responder perguntas a partir do ClickHouse com padrões seguros.
- Quanto custa ClickHouse MCP Server para uma equipe ou em produção?
- O servidor é gratuito. No ClickHouse Cloud Enterprise, a computação custa de US$ 0,33 a US$ 0,52 por unidade-hora (8 GiB, 2 vCPU) e o armazenamento de US$ 22 a US$ 27,50 por TB-mês, conforme a região. Agentes que fazem varreduras sem EXPLAIN ESTIMATE podem acordar serviços ociosos e queimar computação.
- ClickHouse MCP Server é seguro para dados da empresa?
- O servidor pode ler tudo o que for concedido ao seu usuário do ClickHouse, então use um usuário dedicado com privilégio mínimo. Ele roda na sua máquina; nada vai para a empresa ClickHouse, a menos que o seu banco esteja no ClickHouse Cloud. Parâmetros de consulta podem aparecer nos logs de consultas do ClickHouse.
- Quais são as melhores alternativas ao ClickHouse MCP Server?
- As alternativas mais próximas que analisamos são Snowflake-managed MCP Server, MCP Toolbox for Databases e Grafana MCP Server.
Respostas verificadas em 23 de out. de 2026.