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 escritas 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 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 para 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 não definida.

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 Autenticação)

Apenas para desenvolvimento e teste local, 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 quiser experimentar com o ClickHouse SQL Playground, você 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 ambos, 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. No 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 ocorrer durante a exploração. Para permitir instruções DDL ou INSERT/UPDATE, defina a variável de ambiente CLICKHOUSE_ALLOW_WRITE_ACCESS para true. O servidor continua impondo o modo somente leitura se a própria instância do ClickHouse não permitir escritas.

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 adicional de aceitação 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) requerem CLICKHOUSE_ALLOW_WRITE_ACCESS=true
• Operações destrutivas (DROP, TRUNCATE) requerem adicionalmente CLICKHOUSE_ALLOW_DROP=true

Executando Sem uv (Usando Python do Sistema)

Se preferir usar a instalação Python do sistema em vez do uv, você 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 para 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 (ex.: 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 por tenant 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

As seguintes variáveis de ambiente são usadas para configurar as conexões ClickHouse e chDB:

Variáveis ClickHouse

Variáveis Obrigatórias

• CLICKHOUSE_HOST: O hostname do seu servidor ClickHouse
• CLICKHOUSE_USER: O nome de usuário para autenticação
• CLICKHOUSE_PASSWORD: A senha para autenticação

[!CAUTION] É importante tratar seu usuário de banco de dados MCP como faria com qualquer cliente externo conectando-se 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: O número da porta do seu servidor ClickHouse
  • Padrão: 8443 se HTTPS estiver habilitado, 8123 se desabilitado
  • Geralmente não precisa ser definido, a menos que esteja usando uma porta não padrão
• CLICKHOUSE_ROLE: A role a ser usada para autenticação
  • Padrão: Nenhuma
  • Defina isso se seu usuário exigir uma role específica
• CLICKHOUSE_SECURE: Habilitar/desabilitar conexão HTTPS
  • Padrão: "true"
  • Defina como "false" para conexões não seguras
• CLICKHOUSE_VERIFY: Habilitar/desabilitar verificação de certificado SSL
  • Padrão: "true"
  • Defina como "false" para desabilitar a verificação de 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: Hostname do servidor para sobrescrita de SNI e validação de certificado
  • Padrão: Nenhum (usa o hostname da conexão)
  • Isso é útil ao conectar-se através de proxies ou balanceadores de carga onde o hostname do certificado difere do hostname da conexão. Quando definido, este hostname será usado tanto para SNI (Server Name Indication) durante o handshake TLS quanto para validação de hostname do certificado.
• CLICKHOUSE_CONNECT_TIMEOUT: Tempo limite de conexão em segundos
  • 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
  • Padrão: "300"
  • Aumente este valor para consultas de longa duração
• CLICKHOUSE_DATABASE: Banco de dados 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_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 MCP Inspector.
• CLICKHOUSE_MCP_BIND_HOST: Host para vincular o servidor MCP ao usar 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"
• CLICKHOUSE_MCP_BIND_PORT: Porta para vincular o servidor MCP ao usar transporte HTTP ou SSE
  • Padrão: "8000"
  • Usado apenas quando o transporte é "http" ou "sse"
• CLICKHOUSE_MCP_QUERY_TIMEOUT: Tempo limite em segundos para ferramentas SELECT
  • 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 para um provedor de autenticação FastMCP
  • Padrão: Nenhum
  • O valor é o caminho completo da classe de uma subclasse AuthProvider, ex.: 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 definida neste modo
• CLICKHOUSE_MCP_AUTH_DISABLED: Desabilitar autenticação para transportes HTTP/SSE
  • Padrão: "false" (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
• CLICKHOUSE_ENABLED: Habilitar/desabilitar funcionalidade ClickHouse
  • Padrão: "true"
  • Defina como "false" para desabilitar ferramentas ClickHouse ao usar apenas chDB
• CLICKHOUSE_ALLOW_WRITE_ACCESS: Permitir operações de escrita (DDL e DML)
  • 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ó tem efeito quando CLICKHOUSE_ALLOW_WRITE_ACCESS=true também está definido
  • Defina como "true" para permitir explicitamente operações destrutivas DROP e TRUNCATE
  • Este é um recurso de segurança para evitar exclusão acidental de dados durante a exploração por IA

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 para o nome do módulo (sem 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 chDB

• CHDB_ENABLED: Habilitar/desabilitar funcionalidade chDB
  • Padrão: "false"
  • Defina como "true" para habilitar ferramentas chDB
  • Requer a instalação do extra opcional: mcp-clickhouse[chdb]
• CHDB_DATA_PATH: O caminho para o diretório de dados 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 (ex.: /path/to/chdb/data)

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)

Para apenas 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 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 saúde: 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 no YouTube