Servidor MCP do ClickHouse, fornecendo recursos seguros de consulta ao banco de dados ClickHouse para assistentes de IA por meio do protocolo Model Context Protocol
Introdução Detalhada ao Projeto do Servidor MCP ClickHouse
Visão Geral
O servidor MCP ClickHouse é uma implementação do Model Context Protocol (MCP) desenvolvida oficialmente pelo ClickHouse, especificamente para fornecer aos assistentes de IA (como o Claude) uma conexão segura e capacidade de interação com o banco de dados ClickHouse. Este projeto, através do protocolo MCP padronizado, permite que os assistentes de IA executem consultas SQL, gerenciem a estrutura do banco de dados e realizem análises de dados em tempo real.
MCP (Model Context Protocol) é um padrão aberto, projetado para fornecer às aplicações de IA uma forma segura e padronizada de integração de serviços externos. Através deste servidor, os usuários podem permitir que os assistentes de IA acessem diretamente seus bancos de dados ClickHouse, possibilitando consultas e análises de dados inteligentes.
Funcionalidades Principais
1. Execução de Consultas SQL (run_select_query
)
- Descrição da Funcionalidade: Executa consultas SQL no cluster ClickHouse.
- Mecanismo de Segurança: Todas as consultas são executadas no modo
readonly = 1
, garantindo a segurança dos dados. - Parâmetros de Entrada:
sql
(string): A instrução de consulta SQL a ser executada.
- Casos de Uso: Recuperação de dados, análise estatística, geração de relatórios.
2. Gerenciamento de Banco de Dados (list_databases
)
- Descrição da Funcionalidade: Lista todos os bancos de dados no cluster ClickHouse.
- Finalidade: Exploração da estrutura do banco de dados, verificação de permissões.
- Conteúdo Retornado: Lista de bancos de dados acessíveis.
3. Gerenciamento de Tabelas (list_tables
)
- Descrição da Funcionalidade: Lista todas as tabelas em um banco de dados especificado.
- Parâmetros de Entrada:
database
(string): Nome do banco de dados.
- Finalidade: Exploração da estrutura da tabela, compreensão do modelo de dados.
Configuração e Implantação
Integração com Claude Desktop
Caminho de Configuração no macOS
~/Library/Application Support/Claude/claude_desktop_config.json
Caminho de Configuração no Windows
%APPDATA%/Claude/claude_desktop_config.json
Exemplo de Configuração Básica
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.13",
"mcp-clickhouse"
],
"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"
}
}
}
}
Configuração de Variáveis de Ambiente
Variáveis Obrigatórias
CLICKHOUSE_HOST
: Nome do host do servidor ClickHouse.CLICKHOUSE_USER
: Nome de usuário para autenticação.CLICKHOUSE_PASSWORD
: Senha para autenticação.
Variáveis Opcionais
CLICKHOUSE_PORT
: Número da porta.- Padrão: 8443 quando HTTPS está habilitado, 8123 quando desabilitado.
CLICKHOUSE_SECURE
: Habilita/Desabilita a conexão HTTPS.- Padrão: "true"
CLICKHOUSE_VERIFY
: Habilita/Desabilita a verificação do certificado SSL.- Padrão: "true"
CLICKHOUSE_CONNECT_TIMEOUT
: Tempo limite de conexão (segundos).- Padrão: "30"
CLICKHOUSE_SEND_RECEIVE_TIMEOUT
: Tempo limite de envio/recebimento (segundos).- Padrão: "300"
CLICKHOUSE_DATABASE
: Banco de dados padrão para conexão.- Padrão: Nenhum (usa o padrão do servidor).
Casos de Uso
1. Configuração do Playground SQL ClickHouse
{
"env": {
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "demo",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true"
}
}
2. Configuração do Ambiente de Desenvolvimento Local
# Configuração do arquivo .env
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false
3. Configuração do ClickHouse Cloud
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
# Usando as configurações de segurança padrão
Desenvolvimento e Teste
Preparação do Ambiente
# Instalar dependências
uv sync
# Ativar o ambiente virtual
source .venv/bin/activate
# Iniciar o servidor de desenvolvimento
mcp dev mcp_clickhouse/mcp_server.py
Fluxo de Teste
# Instalar dependências de desenvolvimento
uv sync --all-extras --dev
# Verificação de código
uv run ruff check .
# Iniciar os serviços de teste
docker compose up -d test_services
# Executar os testes
uv run pytest tests
Considerações de Segurança
Gerenciamento de Permissões do Banco de Dados
- Princípio do Menor Privilégio: O usuário do banco de dados MCP deve ter apenas as permissões mínimas necessárias.
- Evitar Contas de Administrador: É estritamente proibido usar usuários padrão ou administradores.
- Modo Somente Leitura: Todas as consultas são executadas no modo somente leitura, impedindo a modificação dos dados.
Segurança de Rede
- Conexão HTTPS: Recomenda-se habilitar HTTPS em ambientes de produção.
- Verificação de Certificado: Habilitar a verificação do certificado SSL garante a segurança da conexão.
- Configuração de Tempo Limite: Configurar tempos limite de conexão e consulta razoáveis, evitando o consumo excessivo de recursos.
Características Técnicas
Compatibilidade
- Versão do Python: Suporta Python 3.13.
- Gerenciamento de Dependências: Usa uv para gerenciamento de pacotes.
- Containerização: Suporta implantação com Docker.
- Multiplataforma: Suporta macOS, Windows, Linux.
Otimização de Desempenho
- Pool de Conexões: Gerenciamento eficiente de conexões de banco de dados.
- Controle de Tempo Limite: Tempos limite de conexão e consulta configuráveis.
- Suporte Assíncrono: Suporta execução de consultas assíncronas.
Conclusão
O projeto do servidor MCP ClickHouse constrói uma ponte segura e eficiente entre os assistentes de IA e o banco de dados ClickHouse. Através do protocolo MCP padronizado, ele permite que os assistentes de IA compreendam e operem estruturas de banco de dados complexas, executem consultas SQL sofisticadas e forneçam insights de dados em tempo real.
Principais Vantagens
- Suporte Oficial: Mantido oficialmente pelo ClickHouse, garantindo compatibilidade e estabilidade.
- Design Seguro: Modo somente leitura e controle de permissões integrados, protegendo a segurança dos dados.
- Fácil Integração: Protocolo MCP padronizado, simplificando a integração com aplicações de IA.
- Configuração Flexível: Suporta vários cenários de implantação, desde desenvolvimento local até produção em nuvem.
- Amigável ao Desenvolvimento: Cadeia de ferramentas de desenvolvimento e estrutura de teste completas.
Cenários de Aplicação
- Análise de Dados: Permitir que os assistentes de IA auxiliem em tarefas complexas de análise de dados.
- Inteligência de Negócios: Geração automatizada de relatórios e insights de dados.
- Monitoramento em Tempo Real: Combinar IA para monitorar sistemas e métricas de negócios.
- Exploração de Dados: Explorar a estrutura e o conteúdo do banco de dados através de consultas em linguagem natural.
Este projeto representa uma nova direção na integração de IA e banco de dados, fornecendo aos desenvolvedores uma ferramenta poderosa e segura, permitindo que os assistentes de IA realmente compreendam e operem recursos de dados de nível empresarial.