ClickHouse Cloud & On-Prem

MCP ClickHouse: Operaciones de Base de Datos + Gestión de Cloud

Un servidor integral del Protocolo de Contexto de Modelo (MCP) que proporciona dos capacidades distintas:

1. Operaciones de Base de Datos - Conéctese y consulte cualquier base de datos ClickHouse (local, en la nube o autoalojada)
2. Gestión de Cloud - Gestión completa de la infraestructura de ClickHouse Cloud mediante API

🚀 Inicio Rápido

Comience con nuestro tutorial paso a paso:

👉 Tutorial de Configuración Completo - Transforme a Claude en un potente agente de datos ClickHouse

Para usuarios experimentados, vaya directamente a la sección Configuración Rápida a continuación.

📚 Tabla de Contenidos

• 🚀 Inicio Rápido
• 📚 Tabla de Contenidos
• 🎯 Elija su Caso de Uso
• 🌟 ¿Por Qué Este Servidor?
• ✨ Resumen de Capacidades
• 🔒 Funciones de Seguridad
• ⚡ Configuración Rápida
• 📦 Instalación
• ⚙️ Guía de Configuración
• 🛠️ Herramientas Disponibles
• 💡 Ejemplos de Uso
• 🔧 Desarrollo
• 🐛 Solución de Problemas
• 📄 Licencia

🎯 Elija su Caso de Uso

Este servidor MCP admite dos casos de uso independientes. Puede utilizar uno o ambos:

📊 Solo Operaciones de Base de Datos

Para: Análisis de datos, consultas y exploración de bases de datos ClickHouse

• Conéctese a cualquier instancia de ClickHouse (local, autoalojada o ClickHouse Cloud)
• Ejecute consultas de solo lectura de forma segura
• Explore esquemas de bases de datos y metadatos
• Configuración: Solo credenciales de conexión a la base de datos

☁️ Solo Gestión de Cloud

Para: Gestión programática de la infraestructura de ClickHouse Cloud

• Cree, configure y gestione servicios en la nube
• Gestione claves API, miembros y organizaciones
• Supervise uso, costos y rendimiento
• Configuración: Solo claves API de ClickHouse Cloud

🔄 Ambos Combinados

Para: Flujo de trabajo completo de ClickHouse desde la infraestructura hasta los datos

• Gestione servicios en la nube Y consulte las bases de datos dentro de ellos
• Gestión integral de pipelines de datos de extremo a extremo
• Configuración: Tanto credenciales de base de datos como claves API de la nube

🌟 ¿Por Qué Este Servidor?

Este repositorio mejora significativamente el servidor MCP original de ClickHouse:

[!WARNING] Aviso de Seguridad: El servidor MCP original de ClickHouse (v0.1.10) tiene una falla de seguridad crítica donde run_select_query puede ejecutar CUALQUIER operación SQL, incluidos DROP, DELETE, INSERT, etc., a pesar de que su nombre sugiere que solo ejecuta consultas SELECT. Este servidor implementa filtrado adecuado de consultas y controles de seguridad.

✨ Resumen de Capacidades

📊 Operaciones de Base de Datos (3 Herramientas)

Conéctese y consulte cualquier base de datos ClickHouse:

• Liste bases de datos y tablas con metadatos detallados
• Ejecute consultas SELECT con garantías de seguridad (modo de solo lectura)
• Explore esquemas incluidos tipos de columnas, recuentos de filas y estructuras de tablas
• Funciona con: ClickHouse local, instancias autoalojadas, bases de datos ClickHouse Cloud y el SQL Playground gratuito

☁️ Gestión de Cloud (Más de 50 Herramientas)

Integración completa con la API de ClickHouse Cloud:

• Organizaciones (5 herramientas): Gestione configuraciones, métricas, endpoints privados
• Servicios (12 herramientas): Cree, escale, inicie/detenga, configure y elimine servicios en la nube
• Claves API (5 herramientas): Operaciones CRUD completas para acceso programático
• Miembros e Invitaciones (8 herramientas): Gestión de usuarios y control de acceso
• Copias de Seguridad (4 herramientas): Configure y gestione copias de seguridad automáticas
• ClickPipes (7 herramientas): Gestión de pipelines de ingesta de datos
• Monitoreo (3 herramientas): Análisis de uso, costos y registros de auditoría
• Red (6 herramientas): Endpoints privados y configuración de seguridad

🔒 Funciones de Seguridad

Este servidor MCP incluye controles de seguridad integrales para prevenir modificaciones accidentales de datos o cambios en la infraestructura:

📊 Seguridad de Base de Datos

• Modo de Solo Lectura Automático: Todas las consultas de base de datos se ejecutan con readonly = 1 por defecto
• Filtrado de Consultas: Solo se permiten consultas SELECT, SHOW, DESCRIBE y EXPLAIN
• Anulación Manual: Establezca CLICKHOUSE_READONLY=false para habilitar operaciones de escritura cuando sea necesario

☁️ Seguridad de Gestión de Cloud

• Operaciones Protegidas: Las operaciones destructivas en la nube (eliminar, detener) se pueden habilitar
• Modo Seguro: Establezca CLICKHOUSE_CLOUD_READONLY=false para permitir cambios en la infraestructura
• Registro de Auditoría: Todas las operaciones se registran para fines de responsabilidad

🛡️ Mejores Prácticas de Seguridad

• Privilegios Mínimos: Cree usuarios dedicados con permisos limitados
• SSL por Defecto: Conexiones seguras habilitadas automáticamente
• Variables de Entorno: Las credenciales sensibles nunca se codifican directamente
• Controles de Tiempo de Espera: Previenen consultas y operaciones descontroladas

⚡ Configuración Rápida

Configuración de Claude Desktop

1. Abra su archivo de configuración de Claude Desktop:

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

2. Elija su configuración según su 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: Reemplace /path/to/uv con la ruta absoluta a su ejecutable uv (encuéntrelo con which uv en macOS/Linux)

4. Reinicie Claude Desktop para aplicar los cambios

📦 Instalación

Opción 1: Usando uv (Recomendado)

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

Opción 2: Instalación 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

⚙️ Guía de Configuración

📊 Configuración de Base de Datos

Establezca estas variables de entorno para habilitar las operaciones de base de datos:

Variables Requeridas

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

Variables de Seguridad y Protección

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

Variables Opcionales (con valores predeterminados)

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] Mejor Práctica de Seguridad: Utilice siempre CLICKHOUSE_READONLY=true en entornos de producción. Cree un usuario de base de datos dedicado con privilegios mínimos para las conexiones MCP. Evite usar cuentas administrativas.

☁️ Configuración de API de Cloud

Establezca estas variables de entorno para habilitar la gestión de la nube:

Variables Requeridas

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

Variables de Seguridad y Protección

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

Variables Opcionales (con valores predeterminados)

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

[!WARNING] Seguridad en la Nube: Por defecto, CLICKHOUSE_CLOUD_READONLY=false permite todas las operaciones de infraestructura. Establézcalo en true en producción para prevenir cambios accidentales en la infraestructura. Cuando está deshabilitado, Claude puede crear, modificar y eliminar servicios en la nube, lo que puede generar costos o causar interrupciones del servicio.

🔑 Obtención de Claves API de ClickHouse Cloud

1. Inicie sesión en Consola de ClickHouse Cloud
2. Navegue a Configuración → Claves API
3. Haga clic en Crear Clave API
4. Seleccione los permisos apropiados:
   • Administrador: Acceso completo a todos los recursos
   • Desarrollador: Gestión de servicios y recursos
   • Endpoints de Consulta: Limitado a operaciones de consulta
5. Copie el ID de Clave y el Secreto de Clave a su configuración

🔒 Ejemplos de Configuración de Seguridad

# 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

Ejemplos de Configuración

# 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

🛠️ Herramientas Disponibles

📊 Herramientas de Base de Datos (3 herramientas)

Estas herramientas funcionan con cualquier base de datos ClickHouse cuando se proporciona la configuración de base de datos:

• list_databases() - Liste todas las bases de datos disponibles
• list_tables(database, like?, not_like?) - Liste tablas con metadatos detallados, incluidos esquema, recuentos de filas e información de columnas
• run_query(query) - Ejecute consultas con controles de seguridad:
  • Modo de solo lectura (CLICKHOUSE_READONLY=true): Solo consultas SELECT, SHOW, DESCRIBE, EXPLAIN
  • Modo de acceso completo (CLICKHOUSE_READONLY=false): Todas las operaciones SQL, incluidas INSERT, UPDATE, DELETE, CREATE, DROP

[!NOTE] Seguridad de Consultas: Cuando CLICKHOUSE_READONLY=true, todas las consultas se ejecutan automáticamente con la configuración readonly = 1 y se filtran para prevenir operaciones de modificación de datos.

☁️ Herramientas de Gestión de Cloud (Más de 50 herramientas)

Estas herramientas funcionan con ClickHouse Cloud cuando se proporcionan credenciales API. La disponibilidad de herramientas depende de la configuración CLICKHOUSE_CLOUD_READONLY:

🔍 Operaciones de Solo Lectura (Disponibles cuando CLICKHOUSE_CLOUD_READONLY=true)

Monitoreo de Organizaciones (3 herramientas)

• cloud_list_organizations() - Liste las organizaciones disponibles
• cloud_get_organization(organization_id) - Obtenga detalles de la organización
• cloud_get_organization_metrics(organization_id, filtered_metrics?) - Obtenga métricas de Prometheus

Monitoreo de Servicios (3 herramientas)

• cloud_list_services(organization_id) - Liste todos los servicios en la organización
• cloud_get_service(organization_id, service_id) - Obtenga información detallada del servicio
• cloud_get_service_metrics(organization_id, service_id, filtered_metrics?) - Obtenga métricas de rendimiento del servicio

Inspección de Recursos (8 herramientas)

• cloud_list_api_keys(organization_id) - Liste todas las claves API (solo metadatos)
• cloud_get_api_key(organization_id, key_id) - Obtenga detalles de la clave API
• cloud_list_members(organization_id) - Liste los miembros de la organización
• cloud_get_member(organization_id, user_id) - Obtenga detalles del miembro
• cloud_list_invitations(organization_id) - Liste las invitaciones pendientes
• cloud_get_invitation(organization_id, invitation_id) - Obtenga detalles de la invitación
• cloud_list_backups(organization_id, service_id) - Liste las copias de seguridad del servicio
• cloud_get_backup(organization_id, service_id, backup_id) - Obtenga detalles de la copia de seguridad

Inspección de Configuración (5 herramientas)

• cloud_get_backup_configuration(organization_id, service_id) - Obtenga la configuración de copias de seguridad
• cloud_get_private_endpoint_config(organization_id, service_id) - Obtenga la configuración de endpoints privados
• cloud_list_clickpipes(organization_id, service_id) - Liste los ClickPipes
• cloud_get_clickpipe(organization_id, service_id, clickpipe_id) - Obtenga detalles del ClickPipe
• cloud_get_available_regions() - Obtenga las regiones admitidas

Analítica y Monitoreo (3 herramientas)

• cloud_list_activities(organization_id, from_date?, to_date?) - Obtenga registros de auditoría
• cloud_get_activity(organization_id, activity_id) - Obtenga detalles de actividad
• cloud_get_usage_cost(organization_id, from_date, to_date) - Obtenga análisis de uso

⚠️ Operaciones de Escritura (Disponibles solo cuando CLICKHOUSE_CLOUD_READONLY=false)

Gestión de Organizaciones (2 herramientas)

• cloud_update_organization(organization_id, name?, private_endpoints?) - Actualice la configuración de la organización
• cloud_get_organization_private_endpoint_info(organization_id, cloud_provider, region) - Obtenga información del endpoint privado Gestión de Servicios (9 herramientas)
• cloud_create_service(organization_id, name, provider, region, ...) - Crear nuevo servicio
• cloud_update_service(organization_id, service_id, ...) - Actualizar configuración del servicio
• cloud_update_service_state(organization_id, service_id, command) - Iniciar/detener servicios
• cloud_update_service_scaling(organization_id, service_id, ...) - Configurar escalado (heredado)
• cloud_update_service_replica_scaling(organization_id, service_id, ...) - Configurar escalado de réplicas
• cloud_update_service_password(organization_id, service_id, ...) - Actualizar contraseña del servicio
• cloud_create_service_private_endpoint(organization_id, service_id, id, description) - Crear endpoint privado
• cloud_delete_service(organization_id, service_id) - Eliminar servicio

Gestión de Claves API (3 herramientas)

• cloud_create_api_key(organization_id, name, roles, ...) - Crear nueva clave API
• cloud_update_api_key(organization_id, key_id, ...) - Actualizar propiedades de la clave API
• cloud_delete_api_key(organization_id, key_id) - Eliminar clave API

Gestión de Usuarios (3 herramientas)

• cloud_update_member_role(organization_id, user_id, role) - Actualizar rol de miembro
• cloud_remove_member(organization_id, user_id) - Eliminar miembro
• cloud_create_invitation(organization_id, email, role) - Enviar invitación
• cloud_delete_invitation(organization_id, invitation_id) - Cancelar invitación

Gestión de Infraestructura (12 herramientas)

• cloud_update_backup_configuration(organization_id, service_id, ...) - Actualizar configuración de copias de seguridad
• cloud_create_clickpipe(organization_id, service_id, name, description, source, destination, field_mappings?) - Crear ClickPipe
• cloud_update_clickpipe(organization_id, service_id, clickpipe_id, ...) - Actualizar ClickPipe
• cloud_update_clickpipe_scaling(organization_id, service_id, clickpipe_id, replicas?) - Escalar ClickPipe
• cloud_update_clickpipe_state(organization_id, service_id, clickpipe_id, command) - Controlar estado de ClickPipe
• cloud_delete_clickpipe(organization_id, service_id, clickpipe_id) - Eliminar ClickPipe
• cloud_list_reverse_private_endpoints(organization_id, service_id) - Listar endpoints privados inversos
• cloud_create_reverse_private_endpoint(organization_id, service_id, ...) - Crear endpoint privado inverso
• cloud_get_reverse_private_endpoint(organization_id, service_id, reverse_private_endpoint_id) - Obtener detalles
• cloud_delete_reverse_private_endpoint(organization_id, service_id, reverse_private_endpoint_id) - Eliminar endpoint
• cloud_create_query_endpoint_config(organization_id, service_id, roles, open_api_keys, allowed_origins) - Crear configuración de consulta
• cloud_delete_query_endpoint_config(organization_id, service_id) - Eliminar configuración de consulta

[!CAUTION] Advertencia de Producción: Las operaciones de escritura pueden crear recursos facturables, modificar servicios en ejecución o eliminar infraestructura. Utilice siempre CLICKHOUSE_CLOUD_READONLY=true en producción a menos que se requieran específicamente cambios de infraestructura.

💡 Ejemplos de Uso

📊 Ejemplos de Operaciones de Base de Datos

Modo de Análisis Seguro

# 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 Acceso Completo

# 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")

☁️ Ejemplos de Gestión en la Nube

Modo de Monitoreo (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

Gestión de Infraestructura (Acceso Completo)

# 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"
)

🔄 Ejemplo de Flujo de Trabajo 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)}
""")

🔧 Desarrollo

Configuración de Desarrollo Local

1. Iniciar ClickHouse para pruebas:

   cd test-services
   docker compose up -d
   

2. Crear archivo de entorno:

   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 y ejecutar:

   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
   

Pruebas de Funciones de Seguridad

# 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

Estructura del Proyecto

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)

Ejecución de Pruebas

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

🐛 Solución de Problemas

📊 Problemas de Conexión a la Base de Datos

Problema: No se puede conectar a la base de datos ClickHouse

• ✅ Verifique CLICKHOUSE_HOST, CLICKHOUSE_USER y CLICKHOUSE_PASSWORD
• ✅ Pruebe la conectividad de red: telnet your-host 8443
• ✅ Verifique que el firewall permita conexiones en el puerto especificado
• ✅ Para problemas de SSL, intente configurar CLICKHOUSE_VERIFY=false
• ✅ Asegúrese de que el usuario de la base de datos tenga permisos SELECT apropiados

Problema: La verificación del certificado SSL falla

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

Problema: Las consultas están siendo bloqueadas

• ✅ Verifique si CLICKHOUSE_READONLY=true está impidiendo operaciones de escritura
• ✅ Para desarrollo, configure temporalmente CLICKHOUSE_READONLY=false
• ✅ Revise la consulta para detectar operaciones prohibidas (INSERT, UPDATE, DELETE, CREATE, DROP)
• ✅ Utilice consultas SHOW, DESCRIBE, EXPLAIN o SELECT en su lugar

☁️ Problemas con la API en la Nube

Problema: Las herramientas en la nube no funcionan

• ✅ Verifique que CLICKHOUSE_CLOUD_KEY_ID y CLICKHOUSE_CLOUD_KEY_SECRET sean correctos
• ✅ Compruebe los permisos de la clave API en la Consola de ClickHouse Cloud
• ✅ Asegúrese de que la clave API esté activa y no haya expirado
• ✅ Para problemas de SSL, intente configurar CLICKHOUSE_CLOUD_SSL_VERIFY=false

Problema: Errores de "Operación no permitida"

• ✅ Verifique si CLICKHOUSE_CLOUD_READONLY=true está bloqueando operaciones de escritura
• ✅ Para gestión de infraestructura, configure CLICKHOUSE_CLOUD_READONLY=false
• ✅ Verifique que la clave API tenga permisos suficientes para la operación solicitada
• ✅ Revise el tipo de operación: las operaciones de monitoreo funcionan en modo solo lectura, las operaciones de gestión requieren acceso de escritura

Problema: Errores de "Organización no encontrada"

• ✅ Liste las organizaciones primero: cloud_list_organizations()
• ✅ Verifique que su clave API tenga acceso a la organización
• ✅ Compruebe que está utilizando el formato correcto de ID de organización

🔧 Problemas Generales

Problema: Herramientas faltantes en Claude

• ✅ Las herramientas de base de datos requieren configuración de base de datos (CLICKHOUSE_HOST, etc.)
• ✅ Las herramientas en la nube requieren configuración de API (CLICKHOUSE_CLOUD_KEY_ID, etc.)
• ✅ Verifique la sintaxis del archivo de configuración de Claude Desktop
• ✅ Reinicie Claude Desktop después de los cambios de configuración
• ✅ Verifique que la ruta uv sea absoluta en la configuración

Problema: Las funciones de seguridad no funcionan como se espera

• ✅ Confirme que las variables de entorno estén configuradas correctamente: echo $CLICKHOUSE_READONLY
• ✅ Verifique que los valores booleanos sean cadenas: "true" no true en la configuración JSON
• ✅ Reinicie el servidor MCP después de cambiar la configuración de solo lectura
• ✅ Pruebe primero con operaciones simples para verificar el comportamiento

Problema: Errores de importación o dependencias faltantes

# 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

🔒 Solución de Problemas de Configuración de Seguridad

Problema: Desea habilitar operaciones de escritura temporalmente

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

Problema: Habilitó accidentalmente el modo de escritura en producción

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

Problema: No está claro qué operaciones están bloqueadas

• ✅ El modo solo lectura de base de datos bloquea: INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, TRUNCATE
• ✅ El modo solo lectura de base de datos permite: SELECT, SHOW, DESCRIBE, EXPLAIN, WITH (solo lectura)
• ✅ El modo solo lectura en la nube bloquea: create_, update_, delete_*, iniciar/detener servicios
• ✅ El modo solo lectura en la nube permite: list_, get_, métricas, monitoreo, análisis

📄 Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0. Consulte el archivo LICENSE para más detalles.

Desarrollado por Badr Ouali