ClickHouse

Servidor MCP ClickHouse

Um servidor MCP para ClickHouse.

Funcionalidades

Ferramentas ClickHouse

• run_query

  • Execute consultas SQL no seu cluster ClickHouse.
  • Entrada: query (string): A consulta SQL a ser executada.
  • As consultas são executadas em modo somente leitura por padrão (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), mas gravações podem ser habilitadas explicitamente se necessário.

• list_databases

  • Liste todos os bancos de dados no seu cluster ClickHouse.

• list_tables

  • Liste tabelas em um banco de dados com paginação.
  • Entrada obrigatória: database (string).
  • Entradas opcionais:
    • like / not_like (string): Aplica filtros LIKE ou NOT LIKE aos nomes das tabelas.
    • page_token (string): Token retornado por uma chamada anterior para buscar a próxima página.
    • page_size (int, padrão 50): Número de tabelas retornadas por página.
    • include_detailed_columns (bool, padrão true): Quando false, omite metadados de colunas para respostas mais leves, mantendo o create_table_query completo.
  • Formato da resposta:
    • tables: Array de objetos de tabela para a página atual.
    • next_page_token: Passe este valor de volta para buscar a próxima página, ou null quando não houver mais tabelas.
    • total_tables: Contagem total de tabelas que correspondem aos filtros fornecidos.

Ferramentas chDB

• run_chdb_select_query
  • Execute consultas SQL usando o mecanismo ClickHouse embutido do chDB.
  • Entrada: query (string): A consulta SQL a ser executada.
  • Consulte dados diretamente de várias fontes (arquivos, URLs, bancos de dados) sem processos de ETL.
  • Requer o extra opcional chdb: pip install 'mcp-clickhouse[chdb]'

Endpoint de Verificação de Saúde

Ao executar com transporte HTTP ou SSE, um endpoint de verificação de saúde está disponível em /health. Este endpoint:

• Retorna 200 OK (corpo: OK) se o servidor estiver saudável e puder se conectar ao ClickHouse
• Retorna 503 Service Unavailable com uma mensagem de erro genérica se o servidor não puder se conectar ao ClickHouse

O endpoint é intencionalmente não autenticado para que sondas de orquestradores (ex.: liveness/readiness do Kubernetes, balanceadores de carga) possam acessá-lo sem credenciais. O corpo da resposta é deliberadamente mínimo para evitar vazamento de strings de versão do backend ou detalhes do erro; depure falhas através dos logs do servidor.

Exemplo:

curl http://localhost:8000/health
# Response: OK

Segurança

Autenticação para Transportes HTTP/SSE

Ao usar transporte HTTP ou SSE, a autenticação é obrigatória por padrão. O transporte stdio (padrão) não requer autenticação, pois se comunica apenas via entrada/saída padrão.

Três modos de autenticação são suportados. Escolha um:

Modo	Quando usar	Variável de ambiente
Token de portador estático	Implantações simples, serviços internos	CLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (via FastMCP)	Azure Entra, Google, GitHub, WorkOS, etc.	FASTMCP_SERVER_AUTH=<provider-class-path> (+ variáveis FASTMCP_SERVER_AUTH_* específicas do provedor)
Desabilitado	Apenas desenvolvimento local	CLICKHOUSE_MCP_AUTH_DISABLED=true

A inicialização falha se nenhuma dessas opções estiver configurada para transportes HTTP/SSE.

Configurando a Autenticação

1. Gere um token seguro (pode ser qualquer string aleatória):

   # Using uuidgen (macOS/Linux)
   uuidgen
   
   # Using openssl
   openssl rand -hex 32
   

2. Configure o servidor com o token:

   export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"
   

3. Configure seu cliente MCP para incluir o token nas requisições:

   Para Claude Desktop com transporte HTTP/SSE:

   {
     "mcpServers": {
       "mcp-clickhouse": {
         "url": "http://127.0.0.1:8000",
         "headers": {
           "Authorization": "Bearer your-generated-token"
         }
       }
     }
   }
   

   Nota: o endpoint /health é intencionalmente não autenticado (veja Endpoint de Verificação de Saúde acima). Para verificar se a autenticação por token de portador está realmente rejeitando requisições não autenticadas, acesse o próprio endpoint MCP, por exemplo, com o MCP Inspector, ou fazendo POST de uma requisição JSON-RPC para /mcp com e sem o cabeçalho Authorization e confirmando que a chamada não autenticada retorna 401.

OAuth / OIDC via FastMCP

Para implantações em produção com provedores de identidade (Azure Entra, Google, GitHub, WorkOS, etc.), delegue a autenticação aos provedores de autenticação integrados do FastMCP em vez de usar um token estático. Defina FASTMCP_SERVER_AUTH como o caminho completo da classe de um provedor de autenticação FastMCP, juntamente com as variáveis FASTMCP_SERVER_AUTH_* específicas do provedor, e deixe CLICKHOUSE_MCP_AUTH_TOKEN indefinido.

Exemplo (Azure Entra):

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"

Consulte a documentação do FastMCP para a lista completa de provedores e suas variáveis de ambiente necessárias.

Modo de Desenvolvimento (Desabilitando a Autenticação)

Apenas para desenvolvimento e testes locais, você pode desabilitar a autenticação definindo:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

AVISO: Use isso apenas para desenvolvimento local. Não desabilite a autenticação quando o servidor estiver exposto a qualquer rede.

Configuração

Este servidor MCP suporta tanto ClickHouse quanto chDB. Você pode habilitar um ou ambos, dependendo de suas necessidades.

1. Abra o arquivo de configuração do Claude Desktop localizado em:

   • No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • No Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Adicione o seguinte:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_ROLE": "<clickhouse-role>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Atualize as variáveis de ambiente para apontar para seu próprio serviço ClickHouse.

Ou, se você quiser experimentar com o ClickHouse SQL Playground, pode usar a seguinte configuração:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Para chDB (mecanismo ClickHouse embutido), adicione a seguinte configuração:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Você também pode habilitar ClickHouse e chDB simultaneamente:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "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",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

3. Localize a entrada de comando para uv e substitua-a pelo caminho absoluto para o executável uv. Isso garante que a versão correta do uv seja usada ao iniciar o servidor. Em um Mac, você pode encontrar esse caminho usando which uv.

4. Reinicie o Claude Desktop para aplicar as alterações.

Acesso de Escrita Opcional

Por padrão, este MCP impõe consultas somente leitura para que mutações acidentais não possam acontecer durante a exploração. Para permitir instruções DDL ou INSERT/UPDATE, defina a variável de ambiente CLICKHOUSE_ALLOW_WRITE_ACCESS como true. O servidor continua impondo o modo somente leitura se a própria instância do ClickHouse não permitir gravações.

Proteção contra Operações Destrutivas

Mesmo quando o acesso de escrita está habilitado (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), operações destrutivas (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) exigem uma flag de aceitação adicional por segurança. Isso previne a exclusão acidental de dados durante a exploração por IA.

Para habilitar operações destrutivas, defina ambas as flags:

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}

Esta abordagem em duas camadas garante que exclusões acidentais sejam muito difíceis:

• Operações de escrita (INSERT, UPDATE, CREATE) exigem CLICKHOUSE_ALLOW_WRITE_ACCESS=true
• Operações destrutivas (DROP, TRUNCATE) exigem adicionalmente CLICKHOUSE_ALLOW_DROP=true

Executando sem uv (Usando Python do Sistema)

Se você preferir usar a instalação Python do sistema em vez do uv, pode instalar o pacote do PyPI e executá-lo diretamente:

1. Instale o pacote usando pip:

   python3 -m pip install mcp-clickhouse
   

   Para instalar o suporte ao chDB também:

   python3 -m pip install 'mcp-clickhouse[chdb]'
   

   Para atualizar para a versão mais recente:

   python3 -m pip install --upgrade mcp-clickhouse
   

2. Atualize sua configuração do Claude Desktop para usar Python diretamente:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "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"
      }
    }
  }
}

Alternativamente, você pode usar o script instalado diretamente:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "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"
      }
    }
  }
}

Nota: Certifique-se de usar o caminho completo para o executável Python ou o script mcp-clickhouse se eles não estiverem no PATH do seu sistema. Você pode encontrar os caminhos usando:

• which python3 para o executável Python
• which mcp-clickhouse para o script instalado

Middleware Personalizado

Você pode adicionar middleware personalizado ao servidor MCP sem modificar o código fonte. O FastMCP fornece um sistema de middleware que permite interceptar e processar mensagens do protocolo MCP (chamadas de ferramentas, leituras de recursos, prompts, etc.).

Como Usar

1. Crie um módulo Python com classes de middleware estendendo Middleware e uma função setup_middleware(mcp):

# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())

2. Defina a variável de ambiente MCP_MIDDLEWARE_MODULE como o nome do módulo (sem a extensão .py):

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}

3. Certifique-se de que seu módulo de middleware esteja no caminho de importação do Python (por exemplo, no mesmo diretório onde o servidor MCP é executado ou instalado como um pacote).

Exemplo de Middleware

Um módulo de middleware de exemplo é fornecido em example_middleware.py mostrando padrões comuns:

• Registrando todas as requisições MCP
• Registrando chamadas de ferramentas especificamente
• Medindo o tempo de processamento da requisição

Para usar o exemplo:

"env": {
  "MCP_MIDDLEWARE_MODULE": "example_middleware"
}

Capacidades do Middleware

A classe base Middleware fornece ganchos para diferentes operações MCP:

• on_message(context, call_next) - Chamado para todas as mensagens
• on_request(context, call_next) - Chamado para todas as requisições
• on_notification(context, call_next) - Chamado para todas as notificações
• on_call_tool(context, call_next) - Chamado quando uma ferramenta é executada
• on_read_resource(context, call_next) - Chamado quando um recurso é lido
• on_get_prompt(context, call_next) - Chamado quando um prompt é recuperado
• on_list_tools(context, call_next) - Chamado ao listar ferramentas
• on_list_resources(context, call_next) - Chamado ao listar recursos
• on_list_resource_templates(context, call_next) - Chamado ao listar modelos de recursos
• on_list_prompts(context, call_next) - Chamado ao listar prompts

Cada gancho recebe um objeto MiddlewareContext contendo a mensagem e metadados, e uma função call_next para continuar o pipeline.

Configuração Dinâmica do Cliente via Estado de Contexto

O middleware pode sobrescrever a configuração do cliente ClickHouse por requisição usando a chave de estado de contexto CLIENT_CONFIG_OVERRIDES_KEY. O servidor mescla essas sobrescritas com a configuração base das variáveis de ambiente.

from fastmcp.server.dependencies import get_context
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

Isso permite casos de uso avançados, como ajustes dinâmicos de timeout, roteamento específico de inquilino ou configurações de conexão por usuário.

Desenvolvimento

1. No diretório test-services, execute docker compose up -d para iniciar o cluster ClickHouse.

2. Adicione as seguintes variáveis a um arquivo .env na raiz do repositório.

Nota: O uso do usuário default neste contexto destina-se exclusivamente a fins de desenvolvimento local.

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

3. Execute uv sync para instalar as dependências. Para instalar o uv, siga as instruções aqui. Em seguida, faça source .venv/bin/activate.

4. Para testes fáceis com o MCP Inspector, execute fastmcp dev mcp_clickhouse/mcp_server.py para iniciar o servidor MCP.

5. Para testar com transporte HTTP e o endpoint de verificação de saúde:

   # For development, disable authentication
   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main
   
   # Or with authentication (generate a token first)
   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main
   
   # Then in another terminal:
   curl http://localhost:8000/health
   

Variáveis de Ambiente

A configuração é dividida em grupos independentes. Misturá-los é uma causa comum de falhas de conexão difíceis de depurar:

Grupo	Variáveis	Controla
Conexão com o banco de dados ClickHouse	CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, …	Como este servidor MCP se conecta ao seu cluster ClickHouse através da interface HTTP
Servidor MCP / transporte	CLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*	Transporte MCP, autenticação e limites de execução da ferramenta de consulta
Middleware / chDB	MCP_MIDDLEWARE_MODULE, CHDB_*	Extensões opcionais

[!IMPORTANTE] Variáveis como CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY e CLICKHOUSE_PORT aplicam-se apenas à conexão com o banco de dados ClickHouse. Elas não configuram TLS, portas ou autenticação para o endpoint do protocolo MCP.

Exemplo: se o servidor MCP for executado no Kubernetes atrás de um ingress que termina TLS, isso é uma preocupação do transporte MCP. Mantenha CLICKHOUSE_SECURE alinhado com a forma como o pod alcança o próprio ClickHouse (HTTPS → true, HTTP simples → false). Definir CLICKHOUSE_SECURE=false porque o servidor MCP está atrás de um ingress fará com que o servidor disque para o ClickHouse por HTTP—frequentemente contra uma porta exclusiva para HTTPS—e produza erros opacos de HTTP/TLS nos logs do servidor.

Conexão com o banco de dados ClickHouse

Estas variáveis configuram o cliente HTTP clickhouse-connect e o comportamento das ferramentas baseadas no ClickHouse, como run_query, list_databases e list_tables.

Variáveis obrigatórias

• CLICKHOUSE_HOST: O nome do host do seu servidor ClickHouse (endpoint do banco de dados, não o endereço de vinculação do servidor MCP)
• CLICKHOUSE_USER: O nome de usuário para autenticação no ClickHouse
• CLICKHOUSE_PASSWORD: A senha para autenticação no ClickHouse

[!CAUTION] É importante tratar o usuário MCP do banco de dados como qualquer cliente externo que se conecta ao seu banco de dados, concedendo apenas os privilégios mínimos necessários para sua operação. O uso de usuários padrão ou administrativos deve ser estritamente evitado em todos os momentos.

Variáveis opcionais

• CLICKHOUSE_PORT: Porta da interface HTTP do seu servidor ClickHouse
  • Padrão: 8443 se CLICKHOUSE_SECURE=true, 8123 se CLICKHOUSE_SECURE=false
  • Geralmente não precisa ser definida, a menos que esteja usando uma porta não padrão
  • Deve ser uma porta da interface HTTP, não a porta do protocolo TCP nativo usada pelo clickhouse-client
  • Valores comuns:
    • HTTP: 8123 (simples) / 8443 (TLS) — usada por este servidor e pelo HTTPS do ClickHouse Cloud
    • TCP nativo (não suportado aqui): 9000 (simples) / 9440 (TLS) — usada pelo clickhouse-client
  • Se o servidor responder com Port 9000 is for clickhouse-client program, você está apontando para o protocolo nativo; mude para a porta HTTP (8123/8443 ou o mapeamento HTTP da sua implantação)
• CLICKHOUSE_ROLE: A role do ClickHouse a ser usada para autenticação
  • Padrão: Nenhum
  • Defina isso se o seu usuário exigir uma role específica
• CLICKHOUSE_SECURE: Habilitar HTTPS para a conexão com o banco de dados ClickHouse (não para clientes MCP)
  • Padrão: "true"
  • Defina como "false" somente quando o servidor MCP alcançar o ClickHouse por HTTP simples (típico para Docker Compose local na porta 8123)
  • Deixe como "true" para o ClickHouse Cloud e qualquer endpoint de banco de dados HTTPS — mesmo que o próprio servidor MCP seja exposto via HTTP, stdio ou um ingress que termine o TLS separadamente
  • A incompatibilidade deste sinalizador com a porta do banco de dados (por exemplo, CLICKHOUSE_SECURE=false contra a porta 8443) é um erro de configuração frequente e geralmente se manifesta como erros confusos do cliente HTTP, em vez de uma mensagem clara de "esquema incorreto"
• CLICKHOUSE_VERIFY: Habilitar/desabilitar a verificação do certificado SSL para a conexão HTTPS do ClickHouse
  • Padrão: "true"
  • Defina como "false" para desabilitar a verificação do certificado (não recomendado para produção)
  • Certificados TLS: O pacote usa o armazenamento de confiança do seu sistema operacional para verificação de certificado TLS via truststore. Chamamos truststore.inject_into_ssl() na inicialização para garantir o manuseio adequado do certificado. O comportamento SSL padrão do Python é usado como fallback apenas se ocorrer um erro inesperado.
• CLICKHOUSE_SERVER_HOST_NAME: Nome do host do servidor para substituição de SNI e validação de certificado na conexão com o ClickHouse
  • Padrão: Nenhum (usa o nome do host da conexão)
  • Isso é útil ao conectar-se por meio de proxies ou balanceadores de carga, onde o nome do host do certificado difere do nome do host da conexão. Quando definido, este nome de host será usado tanto para SNI (Indicação de Nome de Servidor) durante o handshake TLS quanto para validação do nome do host do certificado.
• CLICKHOUSE_PROXY_PATH: Prefixo do caminho da URL para o endpoint HTTP do ClickHouse
  • Padrão: Nenhum
  • Defina isso quando a interface HTTP do ClickHouse estiver exposta atrás de um proxy reverso sob um prefixo de caminho (por exemplo, /clickhouse)
• CLICKHOUSE_CONNECT_TIMEOUT: Tempo limite de conexão em segundos para o cliente ClickHouse
  • Padrão: "30"
  • Aumente este valor se você enfrentar tempos limite de conexão
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Tempo limite de envio/recebimento em segundos para o cliente ClickHouse
  • Padrão: "300"
  • Aumente este valor para consultas de longa duração
• CLICKHOUSE_DATABASE: Banco de dados ClickHouse padrão a ser usado
  • Padrão: Nenhum (usa o padrão do servidor)
  • Defina isso para conectar-se automaticamente a um banco de dados específico
• CLICKHOUSE_ENABLED: Habilitar/desabilitar ferramentas de banco de dados ClickHouse
  • Padrão: "true"
  • Defina como "false" para desabilitar as ferramentas do ClickHouse ao usar apenas o chDB
• CLICKHOUSE_ALLOW_WRITE_ACCESS: Permitir operações de gravação (DDL e DML) no ClickHouse
  • Padrão: "false"
  • Defina como "true" para permitir operações DDL (CREATE, ALTER, DROP) e DML (INSERT, UPDATE, DELETE)
  • Quando desabilitado (padrão), as consultas são executadas com a configuração readonly=1 para evitar modificações de dados
• CLICKHOUSE_ALLOW_DROP: Permitir operações destrutivas (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
  • Padrão: "false"
  • Só entra em vigor quando CLICKHOUSE_ALLOW_WRITE_ACCESS=true também estiver definido
  • Defina como "true" para permitir explicitamente operações destrutivas de DROP e TRUNCATE
  • Este é um recurso de segurança para evitar a exclusão acidental de dados durante a exploração por IA

Servidor MCP e transporte

Estas variáveis controlam o próprio processo MCP, incluindo transporte, autenticação e limites de execução da ferramenta de consulta. Elas são independentes das configurações do banco de dados ClickHouse acima. Consulte também Autenticação para transportes HTTP/SSE.

• CLICKHOUSE_MCP_SERVER_TRANSPORT: Define o método de transporte para o servidor MCP
  • Padrão: "stdio"
  • Opções válidas: "stdio", "http", "sse". Isso é útil para desenvolvimento local com ferramentas como o MCP Inspector.
  • stdio é típico para o Claude Desktop; http/sse expõem um listener de rede (host/porta de vinculação abaixo)
• CLICKHOUSE_MCP_BIND_HOST: Host ao qual vincular o servidor MCP ao usar o transporte HTTP ou SSE
  • Padrão: "127.0.0.1"
  • Defina como "0.0.0.0" para vincular a todas as interfaces de rede (útil para Docker ou acesso remoto)
  • Usado apenas quando o transporte é "http" ou "sse" — não relacionado a CLICKHOUSE_HOST
• CLICKHOUSE_MCP_BIND_PORT: Porta à qual vincular o servidor MCP ao usar o transporte HTTP ou SSE
  • Padrão: "8000"
  • Usado apenas quando o transporte é "http" ou "sse" — não relacionado a CLICKHOUSE_PORT
• CLICKHOUSE_MCP_QUERY_TIMEOUT: Tempo limite em segundos para ferramentas de consulta
  • Padrão: "30"
  • Aumente isso se você vir erros Query timed out after ... para consultas pesadas
• CLICKHOUSE_MCP_AUTH_TOKEN: Token de portador estático para transportes HTTP/SSE
  • Padrão: Nenhum
  • Um de CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH ou CLICKHOUSE_MCP_AUTH_DISABLED=true é obrigatório para transportes HTTP/SSE
  • Gere usando uuidgen ou openssl rand -hex 32
  • Os clientes devem enviar este token no cabeçalho Authorization: Bearer <token>
• FASTMCP_SERVER_AUTH: Delegar autenticação a um provedor de autenticação FastMCP
  • Padrão: Nenhum
  • O valor é o caminho completo da classe de uma subclasse AuthProvider, por exemplo, fastmcp.server.auth.providers.azure.AzureProvider ou fastmcp.server.auth.providers.google.GoogleProvider
  • Quando definido, o FastMCP carrega automaticamente o provedor de suas próprias variáveis de ambiente FASTMCP_SERVER_AUTH_*; deixe CLICKHOUSE_MCP_AUTH_TOKEN não definido neste modo
• CLICKHOUSE_MCP_AUTH_DISABLED: Desabilitar autenticação para transportes HTTP/SSE
  • Padrão: "false" (a autenticação está habilitada)
  • Defina como "true" para desabilitar a autenticação apenas para desenvolvimento/teste local
  • AVISO: Use apenas para desenvolvimento local. Não desabilite quando exposto a redes

Variáveis de Middleware

• MCP_MIDDLEWARE_MODULE: Nome do módulo Python contendo middleware personalizado para injetar no servidor MCP
  • Padrão: Nenhum (nenhum middleware carregado)
  • Defina como o nome do módulo (sem a extensão .py) do seu módulo de middleware
  • O módulo deve fornecer uma função setup_middleware(mcp)
  • Consulte Middleware Personalizado para detalhes e exemplos

Variáveis do chDB

• CHDB_ENABLED: Habilitar/desabilitar a funcionalidade do chDB
  • Padrão: "false"
  • Defina como "true" para habilitar as ferramentas do chDB
  • Requer a instalação do extra opcional: mcp-clickhouse[chdb]
• CHDB_DATA_PATH: O caminho para o diretório de dados do chDB
  • Padrão: ":memory:" (banco de dados em memória)
  • Use :memory: para banco de dados em memória
  • Use um caminho de arquivo para armazenamento persistente (por exemplo, /path/to/chdb/data)

Armadilhas comuns de configuração

• CLICKHOUSE_SECURE vs MCP / TLS de ingress — Desligar CLICKHOUSE_SECURE porque o servidor MCP está atrás de um ingress Kubernetes, um proxy reverso ou é acessado por HTTP simples não desabilita o TLS do banco de dados; apenas altera como este processo se conecta ao ClickHouse. Configure o TLS de ingress separadamente das configurações do cliente do banco de dados.
• Portas de protocolo nativo — CLICKHOUSE_PORT deve ter como alvo a interface HTTP do ClickHouse (8123/8443 por padrão). As portas 9000/9440 são para o protocolo TCP nativo (clickhouse-client) e não funcionarão com este servidor.
• Confusão de host — CLICKHOUSE_HOST é o nome do host do banco de dados. CLICKHOUSE_MCP_BIND_HOST é apenas o endereço no qual o servidor MCP HTTP/SSE escuta.

Exemplos de configuração

Para desenvolvimento local com Docker:

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

Para ClickHouse Cloud:

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

Para ClickHouse SQL Playground:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

Apenas para chDB (em memória):

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH defaults to :memory:

Para chDB com armazenamento persistente:

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
CHDB_DATA_PATH=/path/to/chdb/data

Para MCP Inspector ou acesso remoto com transporte HTTP:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)

Para desenvolvimento local com transporte HTTP (autenticação desabilitada):

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!

Ao usar o transporte HTTP, o servidor será executado na porta configurada (padrão 8000). Por exemplo, com a configuração acima:

• Endpoint MCP: http://localhost:4200/mcp
• Verificação de integridade: http://localhost:4200/health

Você pode definir essas variáveis no seu ambiente, em um arquivo .env ou na configuração do Claude Desktop:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
        "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
        "CLICKHOUSE_MCP_BIND_PORT": "8000"
      }
    }
  }
}

Nota: As configurações de host e porta de vinculação são usadas apenas quando o transporte está definido como "http" ou "sse".

Executando testes

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only

Visão geral do YouTube