ClickHouse Cloud & On-Prem

MCP ClickHouse: Operações de Banco de Dados + Gerenciamento na Nuvem

Um servidor abrangente do Model Context Protocol (MCP) que fornece duas capacidades distintas:

1. Operações de Banco de Dados - Conecte-se e consulte qualquer banco de dados ClickHouse (local, nuvem ou auto-hospedado)
2. Gerenciamento na Nuvem - Gerenciamento completo da infraestrutura ClickHouse Cloud via API

🚀 Início Rápido

Comece com nosso tutorial passo a passo:

👉 Tutorial de Configuração Completo - Transforme o Claude em um poderoso agente de dados ClickHouse

Para usuários experientes, vá direto para a seção Configuração Rápida abaixo.

📚 Sumário

• 🚀 Início Rápido
• 📚 Sumário
• 🎯 Escolha Seu Caso de Uso
• 🌟 Por Que Este Servidor?
• ✨ Visão Geral das Capacidades
• 🔒 Recursos de Segurança
• ⚡ Configuração Rápida
• 📦 Instalação
• ⚙️ Guia de Configuração
• 🛠️ Ferramentas Disponíveis
• 💡 Exemplos de Uso
• 🔧 Desenvolvimento
• 🐛 Solução de Problemas
• 📄 Licença

🎯 Escolha Seu Caso de Uso

Este servidor MCP suporta dois casos de uso independentes. Você pode usar um ou ambos:

📊 Somente Operações de Banco de Dados

Para: Análise de dados, consultas e exploração de bancos de dados ClickHouse

• Conecte-se a qualquer instância ClickHouse (local, auto-hospedada ou ClickHouse Cloud)
• Execute consultas somente leitura com segurança
• Explore esquemas de banco de dados e metadados
• Configuração: Apenas credenciais de conexão do banco de dados

☁️ Somente Gerenciamento na Nuvem

Para: Gerenciar a infraestrutura ClickHouse Cloud programaticamente

• Crie, configure e gerencie serviços na nuvem
• Gerencie chaves de API, membros e organizações
• Monitore uso, custos e desempenho
• Configuração: Apenas chaves de API do ClickHouse Cloud

🔄 Ambos Combinados

Para: Fluxo de trabalho completo do ClickHouse, da infraestrutura aos dados

• Gerencie serviços na nuvem E consulte os bancos de dados dentro deles
• Gerenciamento de pipeline de dados de ponta a ponta
• Configuração: Credenciais de banco de dados e chaves de API da nuvem

🌟 Por Que Este Servidor?

Este repositório melhora significativamente o servidor MCP ClickHouse original:

[!WARNING] Aviso de Segurança: O servidor MCP ClickHouse original (v0.1.10) tem uma falha crítica de segurança onde run_select_query pode executar QUALQUER operação SQL, incluindo DROP, DELETE, INSERT, etc., apesar do nome sugerir que ele apenas executa consultas SELECT. Este servidor implementa filtragem adequada de consultas e controles de segurança.

✨ Visão Geral das Capacidades

📊 Operações de Banco de Dados (3 Ferramentas)

Conecte-se e consulte qualquer banco de dados ClickHouse:

• Liste bancos de dados e tabelas com metadados detalhados
• Execute consultas SELECT com garantias de segurança (modo somente leitura)
• Explore esquemas incluindo tipos de colunas, contagens de linhas e estruturas de tabelas
• Funciona com: ClickHouse local, instâncias auto-hospedadas, bancos de dados ClickHouse Cloud e o SQL Playground gratuito

☁️ Gerenciamento na Nuvem (Mais de 50 Ferramentas)

Integração completa com a API ClickHouse Cloud:

• Organizações (5 ferramentas): Gerencie configurações, métricas, endpoints privados
• Serviços (12 ferramentas): Crie, dimensione, inicie/pare, configure, exclua serviços na nuvem
• Chaves de API (5 ferramentas): Operações CRUD completas para acesso programático
• Membros e Convites (8 ferramentas): Gerenciamento de usuários e controle de acesso
• Backups (4 ferramentas): Configure e gerencie backups automatizados
• ClickPipes (7 ferramentas): Gerenciamento de pipelines de ingestão de dados
• Monitoramento (3 ferramentas): Análises de uso, custos e logs de auditoria
• Rede (6 ferramentas): Endpoints privados e configuração de segurança

🔒 Recursos de Segurança

Este servidor MCP inclui controles de segurança abrangentes para evitar modificação acidental de dados ou alterações na infraestrutura:

📊 Segurança do Banco de Dados

• Modo Somente Leitura Automático: Todas as consultas ao banco de dados são executadas com readonly = 1 por padrão
• Filtragem de Consultas: Apenas consultas SELECT, SHOW, DESCRIBE e EXPLAIN são permitidas
• Substituição Manual: Defina CLICKHOUSE_READONLY=false para habilitar operações de escrita quando necessário

☁️ Segurança do Gerenciamento na Nuvem

• Operações Protegidas: Operações destrutivas na nuvem (excluir, parar) podem ser habilitadas
• Modo Seguro: Defina CLICKHOUSE_CLOUD_READONLY=false para permitir alterações na infraestrutura
• Trilha de Auditoria: Todas as operações são registradas para responsabilização

🛡️ Melhores Práticas de Segurança

• Privilégios Mínimos: Crie usuários dedicados com permissões limitadas
• SSL por Padrão: Conexões seguras habilitadas automaticamente
• Variáveis de Ambiente: Credenciais sensíveis nunca são codificadas
• Controles de Tempo Limite: Evite consultas e operações sem controle

⚡ Configuração Rápida

Configuração do Claude Desktop

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

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

2. Escolha sua configuração com base no seu caso de uso:

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-server.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "your-username",
        "CLICKHOUSE_PASSWORD": "your-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-instance.clickhouse.cloud",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "your-database-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_CLOUD_KEY_ID": "your-cloud-key-id",
        "CLICKHOUSE_CLOUD_KEY_SECRET": "your-cloud-key-secret"
      }
    }
  }
}

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-instance.clickhouse.cloud",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "your-database-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true",
        "CLICKHOUSE_CLOUD_KEY_ID": "your-cloud-key-id",
        "CLICKHOUSE_CLOUD_KEY_SECRET": "your-cloud-key-secret"
      }
    }
  }
}

3. Importante: Substitua /path/to/uv pelo caminho absoluto para o executável uv (encontre-o com which uv no macOS/Linux)

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

📦 Instalação

Opção 1: Usando uv (Recomendado)

# Install via uv (used by Claude Desktop)
uv add chmcp

Opção 2: Instalação Manual

# Clone the repository
git clone https://github.com/oualib/chmcp.git
cd chmcp

# Install core dependencies
pip install .

# Install with development dependencies
pip install ".[dev]"

# Install with test dependencies
pip install ".[test]"

# Install with documentation dependencies
pip install ".[docs]"

# Install with all optional dependencies
pip install ".[dev,test,docs]"

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

⚙️ Guia de Configuração

📊 Configuração do Banco de Dados

Defina estas variáveis de ambiente para habilitar operações de banco de dados:

Variáveis Obrigatórias

CLICKHOUSE_HOST=your-clickhouse-host.com   # ClickHouse server hostname
CLICKHOUSE_USER=your-username              # Username for authentication
CLICKHOUSE_PASSWORD=your-password          # Password for authentication

Variáveis de Segurança e Proteção

CLICKHOUSE_READONLY=true                   # Enable read-only mode (recommended)
                                           # true: Only SELECT/SHOW/DESCRIBE queries allowed
                                           # false: All SQL operations permitted

Variáveis Opcionais (com padrões)

CLICKHOUSE_PORT=8443                        # 8443 for HTTPS, 8123 for HTTP
CLICKHOUSE_SECURE=true                      # Enable HTTPS connection
CLICKHOUSE_VERIFY=true                      # Verify SSL certificates
CLICKHOUSE_CONNECT_TIMEOUT=30               # Connection timeout in seconds
CLICKHOUSE_SEND_RECEIVE_TIMEOUT=300         # Query timeout in seconds
CLICKHOUSE_DATABASE=default                 # Default database to use

[!CAUTION] Melhor Prática de Segurança: Sempre use CLICKHOUSE_READONLY=true em ambientes de produção. Crie um usuário de banco de dados dedicado com privilégios mínimos para conexões MCP. Evite usar contas administrativas.

☁️ Configuração da API na Nuvem

Defina estas variáveis de ambiente para habilitar o gerenciamento na nuvem:

Variáveis Obrigatórias

CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id          # From ClickHouse Cloud Console
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret  # From ClickHouse Cloud Console

Variáveis de Segurança e Proteção

CLICKHOUSE_CLOUD_READONLY=false            # Cloud operation mode (default: false)
                                           # true: Only read operations (list, get, metrics)
                                           # false: All cloud operations permitted (create, update, delete)

Variáveis Opcionais (com padrões)

CLICKHOUSE_CLOUD_API_URL=https://api.clickhouse.cloud   # API endpoint
CLICKHOUSE_CLOUD_TIMEOUT=30                             # Request timeout
CLICKHOUSE_CLOUD_SSL_VERIFY=true                        # SSL verification

[!WARNING] Segurança na Nuvem: Por padrão, CLICKHOUSE_CLOUD_READONLY=false permite todas as operações de infraestrutura. Defina como true em produção para evitar alterações acidentais na infraestrutura. Quando desabilitado, o Claude pode criar, modificar e excluir serviços na nuvem, o que pode gerar custos ou causar interrupções no serviço.

🔑 Obtendo Chaves de API do ClickHouse Cloud

1. Faça login no Console do ClickHouse Cloud
2. Navegue até Configurações → Chaves de API
3. Clique em Criar Chave de API
4. Selecione as permissões apropriadas:
   • Admin: Acesso completo a todos os recursos
   • Desenvolvedor: Gerenciamento de serviços e recursos
   • Endpoints de Consulta: Limitado a operações de consulta
5. Copie o ID da Chave e o Segredo da Chave para sua configuração

🔒 Exemplos de Configuração de Segurança

# Database - read-only queries only
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=readonly_user
CLICKHOUSE_PASSWORD=secure-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# Cloud - monitoring and inspection only (explicitly set to true)
CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret
CLICKHOUSE_CLOUD_READONLY=true

# Database - all operations allowed
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_READONLY=false

# Cloud - full infrastructure management
CLICKHOUSE_CLOUD_KEY_ID=dev-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=dev-key-secret
CLICKHOUSE_CLOUD_READONLY=false

# Database - read-only for data analysis
CLICKHOUSE_HOST=analytics.company.com
CLICKHOUSE_USER=analyst
CLICKHOUSE_PASSWORD=analyst-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# Cloud - monitoring only, no infrastructure changes
CLICKHOUSE_CLOUD_KEY_ID=monitoring-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=monitoring-key-secret
CLICKHOUSE_CLOUD_READONLY=true

Exemplos de Configuração

# Database only - full access for development
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_PORT=8123
CLICKHOUSE_READONLY=false

# Database connection - read-only
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-database-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# Cloud management - monitoring only (explicitly set to true)
CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret
CLICKHOUSE_CLOUD_READONLY=true

# Disable SSL verification for database
CLICKHOUSE_VERIFY=false
CLICKHOUSE_SECURE=false  # Use HTTP instead of HTTPS
CLICKHOUSE_PORT=8123     # HTTP port instead of 8443

# Disable SSL verification for cloud API
CLICKHOUSE_CLOUD_SSL_VERIFY=false

🛠️ Ferramentas Disponíveis

📊 Ferramentas de Banco de Dados (3 ferramentas)

Estas ferramentas funcionam com qualquer banco de dados ClickHouse quando a configuração do banco de dados é fornecida:

• list_databases() - Liste todos os bancos de dados disponíveis
• list_tables(database, like?, not_like?) - Liste tabelas com metadados detalhados, incluindo esquema, contagens de linhas e informações de colunas
• run_query(query) - Execute consultas com controles de segurança:
  • Modo somente leitura (CLICKHOUSE_READONLY=true): Apenas consultas SELECT, SHOW, DESCRIBE, EXPLAIN
  • Modo de acesso completo (CLICKHOUSE_READONLY=false): Todas as operações SQL, incluindo INSERT, UPDATE, DELETE, CREATE, DROP

[!NOTE] Segurança de Consultas: Quando CLICKHOUSE_READONLY=true, todas as consultas são executadas automaticamente com a configuração readonly = 1 e são filtradas para evitar operações de modificação de dados.

☁️ Ferramentas de Gerenciamento na Nuvem (mais de 50 ferramentas)

Estas ferramentas funcionam com o ClickHouse Cloud quando as credenciais da API são fornecidas. A disponibilidade das ferramentas depende da configuração CLICKHOUSE_CLOUD_READONLY:

🔍 Operações Somente Leitura (Disponíveis quando CLICKHOUSE_CLOUD_READONLY=true)

Monitoramento da Organização (3 ferramentas)

• cloud_list_organizations() - Liste organizações disponíveis
• cloud_get_organization(organization_id) - Obtenha detalhes da organização
• cloud_get_organization_metrics(organization_id, filtered_metrics?) - Obtenha métricas do Prometheus

Monitoramento de Serviços (3 ferramentas)

• cloud_list_services(organization_id) - Liste todos os serviços na organização
• cloud_get_service(organization_id, service_id) - Obtenha informações detalhadas do serviço
• cloud_get_service_metrics(organization_id, service_id, filtered_metrics?) - Obtenha métricas de desempenho do serviço

Inspeção de Recursos (8 ferramentas)

• cloud_list_api_keys(organization_id) - Liste todas as chaves de API (apenas metadados)
• cloud_get_api_key(organization_id, key_id) - Obtenha detalhes da chave de API
• cloud_list_members(organization_id) - Liste membros da organização
• cloud_get_member(organization_id, user_id) - Obtenha detalhes do membro
• cloud_list_invitations(organization_id) - Liste convites pendentes
• cloud_get_invitation(organization_id, invitation_id) - Obtenha detalhes do convite
• cloud_list_backups(organization_id, service_id) - Liste backups de serviços
• cloud_get_backup(organization_id, service_id, backup_id) - Obtenha detalhes do backup

Inspeção de Configuração (5 ferramentas)

• cloud_get_backup_configuration(organization_id, service_id) - Obtenha configuração de backup
• cloud_get_private_endpoint_config(organization_id, service_id) - Obtenha configuração de endpoint privado
• cloud_list_clickpipes(organization_id, service_id) - Liste ClickPipes
• cloud_get_clickpipe(organization_id, service_id, clickpipe_id) - Obtenha detalhes do ClickPipe
• cloud_get_available_regions() - Obtenha regiões suportadas

Análises e Monitoramento (3 ferramentas)

• cloud_list_activities(organization_id, from_date?, to_date?) - Obtenha logs de auditoria
• cloud_get_activity(organization_id, activity_id) - Obtenha detalhes da atividade
• cloud_get_usage_cost(organization_id, from_date, to_date) - Obtenha análises de uso

⚠️ Operações de Escrita (Disponíveis apenas quando CLICKHOUSE_CLOUD_READONLY=false)

Gerenciamento da Organização (2 ferramentas)

• cloud_update_organization(organization_id, name?, private_endpoints?) - Atualize configurações da organização
• cloud_get_organization_private_endpoint_info(organization_id, cloud_provider, region) - Obtenha informações do endpoint privado Gerenciamento de Serviços (9 ferramentas)
• cloud_create_service(organization_id, name, provider, region, ...) - Criar novo serviço
• cloud_update_service(organization_id, service_id, ...) - Atualizar configurações do serviço
• cloud_update_service_state(organization_id, service_id, command) - Iniciar/parar serviços
• cloud_update_service_scaling(organization_id, service_id, ...) - Configurar escalonamento (legado)
• cloud_update_service_replica_scaling(organization_id, service_id, ...) - Configurar escalonamento de réplicas
• cloud_update_service_password(organization_id, service_id, ...) - Atualizar senha do serviço
• cloud_create_service_private_endpoint(organization_id, service_id, id, description) - Criar endpoint privado
• cloud_delete_service(organization_id, service_id) - Excluir serviço

Gerenciamento de Chaves de API (3 ferramentas)

• cloud_create_api_key(organization_id, name, roles, ...) - Criar nova chave de API
• cloud_update_api_key(organization_id, key_id, ...) - Atualizar propriedades da chave de API
• cloud_delete_api_key(organization_id, key_id) - Excluir chave de API

Gerenciamento de Usuários (3 ferramentas)

• cloud_update_member_role(organization_id, user_id, role) - Atualizar função do membro
• cloud_remove_member(organization_id, user_id) - Remover membro
• cloud_create_invitation(organization_id, email, role) - Enviar convite
• cloud_delete_invitation(organization_id, invitation_id) - Cancelar convite

Gerenciamento de Infraestrutura (12 ferramentas)

• cloud_update_backup_configuration(organization_id, service_id, ...) - Atualizar configurações de backup
• cloud_create_clickpipe(organization_id, service_id, name, description, source, destination, field_mappings?) - Criar ClickPipe
• cloud_update_clickpipe(organization_id, service_id, clickpipe_id, ...) - Atualizar ClickPipe
• cloud_update_clickpipe_scaling(organization_id, service_id, clickpipe_id, replicas?) - Escalonar ClickPipe
• cloud_update_clickpipe_state(organization_id, service_id, clickpipe_id, command) - Controlar estado do ClickPipe
• cloud_delete_clickpipe(organization_id, service_id, clickpipe_id) - Excluir ClickPipe
• cloud_list_reverse_private_endpoints(organization_id, service_id) - Listar endpoints privados reversos
• cloud_create_reverse_private_endpoint(organization_id, service_id, ...) - Criar endpoint privado reverso
• cloud_get_reverse_private_endpoint(organization_id, service_id, reverse_private_endpoint_id) - Obter detalhes
• cloud_delete_reverse_private_endpoint(organization_id, service_id, reverse_private_endpoint_id) - Excluir endpoint
• cloud_create_query_endpoint_config(organization_id, service_id, roles, open_api_keys, allowed_origins) - Criar configuração de consulta
• cloud_delete_query_endpoint_config(organization_id, service_id) - Excluir configuração de consulta

[!CAUTION] Aviso de Produção: Operações de escrita podem criar recursos faturáveis, modificar serviços em execução ou excluir infraestrutura. Sempre use CLICKHOUSE_CLOUD_READONLY=true em produção, a menos que alterações de infraestrutura sejam especificamente necessárias.

💡 Exemplos de Uso

📊 Exemplos de Operações de Banco de Dados

Modo de Análise Segura

# With CLICKHOUSE_READONLY=true (recommended for production)
# Only analytical queries are allowed

# Explore database structure
databases = list_databases()
print(f"Available databases: {[db['name'] for db in databases]}")

# Get detailed table information
tables = list_tables("my_database")
for table in tables:
    print(f"Table: {table['name']}, Rows: {table['total_rows']}")

# Execute analytical queries safely
result = run_query("""
    SELECT 
        date_trunc('day', timestamp) as day,
        count(*) as events,
        avg(value) as avg_value
    FROM my_table 
    WHERE timestamp >= '2024-01-01'
    GROUP BY day
    ORDER BY day
""")

# These queries would be blocked in readonly mode:
# run_query("DROP TABLE my_table")  # ❌ Blocked
# run_query("INSERT INTO my_table VALUES (1)")  # ❌ Blocked
# run_query("UPDATE my_table SET value = 0")  # ❌ Blocked

Modo de Acesso Total

# With CLICKHOUSE_READONLY=false (development only)
# All SQL operations are allowed

# Data modification operations
run_query("""
    CREATE TABLE test_table (
        id UInt32,
        name String,
        created_at DateTime
    ) ENGINE = MergeTree()
    ORDER BY id
""")

run_query("INSERT INTO test_table VALUES (1, 'test', now())")
run_query("UPDATE test_table SET name = 'updated' WHERE id = 1")

☁️ Exemplos de Gerenciamento na Nuvem

Modo de Monitoramento (Seguro)

# With CLICKHOUSE_CLOUD_READONLY=true (recommended for production)
# Only monitoring and inspection operations

# Monitor organization resources
orgs = cloud_list_organizations()
for org in orgs:
    services = cloud_list_services(org['id'])
    print(f"Organization: {org['name']}, Services: {len(services)}")
    
    # Get service metrics
    for service in services:
        metrics = cloud_get_service_metrics(org['id'], service['id'])
        print(f"Service {service['name']} metrics: {metrics}")

# Monitor costs and usage
usage = cloud_get_usage_cost(
    organization_id="org-123",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(f"Monthly cost: ${usage['total_cost']}")

# Audit recent activities
activities = cloud_list_activities(
    organization_id="org-123",
    from_date="2024-01-01T00:00:00Z"
)
print(f"Recent activities: {len(activities)} events")

# These operations would be blocked in readonly mode:
# cloud_create_service(...)  # ❌ Blocked
# cloud_delete_service(...)  # ❌ Blocked  
# cloud_update_service_state(...)  # ❌ Blocked

Gerenciamento de Infraestrutura (Acesso Total)

# With CLICKHOUSE_CLOUD_READONLY=false (use with caution)
# All infrastructure operations allowed

# Create a production service with full configuration
service = cloud_create_service(
    organization_id="org-123",
    name="analytics-prod",
    provider="aws",
    region="us-east-1",
    tier="production",
    min_replica_memory_gb=32,
    max_replica_memory_gb=256,
    num_replicas=3,
    idle_scaling=True,
    idle_timeout_minutes=10,
    ip_access_list=[
        {"source": "10.0.0.0/8", "description": "Internal network"},
        {"source": "203.0.113.0/24", "description": "Office network"}
    ]
)

# Start the service and monitor status
cloud_update_service_state(
    organization_id="org-123",
    service_id=service['id'],
    command="start"
)

# Set up automated backups
cloud_update_backup_configuration(
    organization_id="org-123",
    service_id=service['id'],
    backup_period_in_hours=24,
    backup_retention_period_in_hours=168,  # 7 days
    backup_start_time="02:00"
)

🔄 Exemplo de Fluxo de Trabalho Combinado Seguro

# Production-safe configuration for monitoring and analysis
# CLICKHOUSE_READONLY=true + CLICKHOUSE_CLOUD_READONLY=true

# 1. Monitor existing cloud infrastructure
orgs = cloud_list_organizations()
org_id = orgs[0]['id']

services = cloud_list_services(org_id)
active_services = [s for s in services if s['state'] == 'running']
print(f"Active services: {len(active_services)}")

# 2. Analyze data from running services
for service in active_services:
    # Check service health
    metrics = cloud_get_service_metrics(org_id, service['id'])
    
    # Analyze data (read-only queries)
    if service['endpoints']:
        # Connect to database (would use service endpoint)
        result = run_query("""
            SELECT 
                database,
                table,
                sum(rows) as total_rows,
                sum(bytes_on_disk) as disk_usage
            FROM system.parts
            WHERE active = 1
            GROUP BY database, table
            ORDER BY total_rows DESC
            LIMIT 10
        """)
        
        print(f"Top tables in {service['name']}: {result}")

# 3. Generate usage report
usage = cloud_get_usage_cost(
    organization_id=org_id,
    from_date="2024-01-01",
    to_date="2024-01-31"
)

activities = cloud_list_activities(org_id)
recent_changes = [a for a in activities if 'create' in a.get('action', '').lower()]

print(f"""
Monthly Report:
- Total Cost: ${usage.get('total_cost', 'N/A')}
- Active Services: {len(active_services)}
- Recent Infrastructure Changes: {len(recent_changes)}
""")

🔧 Desenvolvimento

Configuração de Desenvolvimento Local

1. Iniciar ClickHouse para testes:

   cd test-services
   docker compose up -d
   

2. Criar arquivo de ambiente:

   cat > .env << EOF
   # Database configuration (development mode)
   CLICKHOUSE_HOST=localhost
   CLICKHOUSE_PORT=8123
   CLICKHOUSE_USER=default
   CLICKHOUSE_PASSWORD=clickhouse
   CLICKHOUSE_SECURE=false
   CLICKHOUSE_READONLY=false
   
   # Cloud configuration (optional, safe mode)
   CLICKHOUSE_CLOUD_KEY_ID=your-key-id
   CLICKHOUSE_CLOUD_KEY_SECRET=your-key-secret
   CLICKHOUSE_CLOUD_READONLY=true
   EOF
   

3. Instalar e executar:

   uv sync                               # Install dependencies
   source .venv/bin/activate            # Activate virtual environment
   mcp dev chmcp/mcp_server.py          # Start for testing
   # OR
   python -m chmcp.main                 # Start normally
   

Testando Recursos de Segurança

# Test read-only database mode
CLICKHOUSE_READONLY=true python -m chmcp.main

# Test cloud monitoring mode  
CLICKHOUSE_CLOUD_READONLY=true python -m chmcp.main

# Test full access mode (development only)
CLICKHOUSE_READONLY=false CLICKHOUSE_CLOUD_READONLY=false python -m chmcp.main

Estrutura do Projeto

chmcp/
├── __init__.py                 # Package initialization
├── main.py                     # Entry point
├── mcp_env.py                  # Database environment configuration
├── mcp_server.py              # Main server + database tools (3 tools)
├── cloud_config.py            # Cloud API configuration
├── cloud_client.py            # HTTP client for Cloud API
└── cloud_tools.py             # Cloud MCP tools (50+ tools)

Executando Testes

uv sync --all-extras --dev              # Install dev dependencies
uv run ruff check .                     # Run linting
docker compose up -d                    # Start test ClickHouse
uv run pytest tests                     # Run tests

🐛 Solução de Problemas

📊 Problemas de Conexão com o Banco de Dados

Problema: Não é possível conectar ao banco de dados ClickHouse

• ✅ Verifique CLICKHOUSE_HOST, CLICKHOUSE_USER e CLICKHOUSE_PASSWORD
• ✅ Teste a conectividade de rede: telnet your-host 8443
• ✅ Verifique se as configurações de firewall permitem conexões na porta especificada
• ✅ Para problemas de SSL, tente definir CLICKHOUSE_VERIFY=false
• ✅ Garanta que o usuário do banco tenha permissões SELECT apropriadas

Problema: A verificação do certificado SSL falha

# Temporarily disable SSL verification
CLICKHOUSE_VERIFY=false
CLICKHOUSE_SECURE=false  # Use HTTP instead of HTTPS
CLICKHOUSE_PORT=8123     # HTTP port instead of 8443

Problema: Consultas estão sendo bloqueadas

• ✅ Verifique se CLICKHOUSE_READONLY=true está impedindo operações de escrita
• ✅ Para desenvolvimento, defina temporariamente CLICKHOUSE_READONLY=false
• ✅ Revise a consulta para operações proibidas (INSERT, UPDATE, DELETE, CREATE, DROP)
• ✅ Use consultas SHOW, DESCRIBE, EXPLAIN ou SELECT em vez disso

☁️ Problemas com a API da Nuvem

Problema: Ferramentas da nuvem não estão funcionando

• ✅ Verifique se CLICKHOUSE_CLOUD_KEY_ID e CLICKHOUSE_CLOUD_KEY_SECRET estão corretos
• ✅ Verifique as permissões da chave de API no Console da ClickHouse Cloud
• ✅ Garanta que a chave de API esteja ativa e não expirada
• ✅ Para problemas de SSL, tente definir CLICKHOUSE_CLOUD_SSL_VERIFY=false

Problema: Erros de "Operação não permitida"

• ✅ Verifique se CLICKHOUSE_CLOUD_READONLY=true está bloqueando operações de escrita
• ✅ Para gerenciamento de infraestrutura, defina CLICKHOUSE_CLOUD_READONLY=false
• ✅ Verifique se a chave de API tem permissões suficientes para a operação solicitada
• ✅ Revise o tipo de operação: operações de monitoramento funcionam em modo somente leitura, operações de gerenciamento exigem acesso de escrita

Problema: Erros de "Organização não encontrada"

• ✅ Liste as organizações primeiro: cloud_list_organizations()
• ✅ Verifique se sua chave de API tem acesso à organização
• ✅ Verifique se você está usando o formato correto do ID da organização

🔧 Problemas Gerais

Problema: Ferramentas ausentes no Claude

• ✅ Ferramentas de banco de dados exigem configuração do banco (CLICKHOUSE_HOST, etc.)
• ✅ Ferramentas da nuvem exigem configuração da API (CLICKHOUSE_CLOUD_KEY_ID, etc.)
• ✅ Verifique a sintaxe do arquivo de configuração do Claude Desktop
• ✅ Reinicie o Claude Desktop após alterações na configuração
• ✅ Verifique se o caminho uv é absoluto na configuração

Problema: Recursos de segurança não funcionando como esperado

• ✅ Confirme se as variáveis de ambiente estão definidas corretamente: echo $CLICKHOUSE_READONLY
• ✅ Verifique se os valores booleanos são strings: "true" não true na configuração JSON
• ✅ Reinicie o servidor MCP após alterar as configurações de somente leitura
• ✅ Teste com operações simples primeiro para verificar o comportamento

Problema: Erros de importação ou dependências ausentes

# Reinstall with latest dependencies
uv sync --force
# Core dependencies with force reinstall
pip install . --force-reinstall

# With development dependencies
pip install ".[dev]" --force-reinstall

# With all optional dependencies
pip install ".[dev,test,docs]" --force-reinstall

# Editable install with force reinstall
pip install -e ".[dev]" --force-reinstall

🔒 Solução de Problemas de Configuração de Segurança

Problema: Deseja habilitar operações de escrita temporariamente

# For database operations
export CLICKHOUSE_READONLY=false
# For cloud operations  
export CLICKHOUSE_CLOUD_READONLY=false
# Restart MCP server

Problema: Habilitou acidentalmente o modo de escrita em produção

# Immediately disable write operations
export CLICKHOUSE_READONLY=true
export CLICKHOUSE_CLOUD_READONLY=true
# Restart MCP server
# Review audit logs: cloud_list_activities()

Problema: Não está claro quais operações estão bloqueadas

• ✅ O modo somente leitura do banco bloqueia: INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, TRUNCATE
• ✅ O modo somente leitura do banco permite: SELECT, SHOW, DESCRIBE, EXPLAIN, WITH (somente leitura)
• ✅ O modo somente leitura da nuvem bloqueia: create_, update_, delete_*, iniciar/parar serviços
• ✅ O modo somente leitura da nuvem permite: list_, get_, métricas, monitoramento, análises

📄 Licença

Este projeto está licenciado sob a Apache License 2.0. Consulte o arquivo LICENSE para obter detalhes.

Desenvolvido por Badr Ouali