Servidor MCP de ClickHouse

Un servidor MCP para ClickHouse.

Características

Herramientas

run_select_query
- Ejecute consultas SQL en su clúster ClickHouse.
- Entrada: sql (cadena): la consulta SQL a ejecutar.
- Todas las consultas de ClickHouse se ejecutan con readonly = 1 para garantizar que sean seguras.
list_databases
- Enumere todas las bases de datos en su clúster ClickHouse.
list_tables
- Enumerar todas las tablas de una base de datos.
- Entrada: database (cadena): el nombre de la base de datos.

Configuración

Abra el archivo de configuración de Claude Desktop ubicado en:
- En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- En Windows: %APPDATA%/Claude/claude_desktop_config.json
Añade lo siguiente:

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

Actualice las variables de entorno para que apunten a su propio servicio ClickHouse.

O, si desea probarlo con ClickHouse SQL Playground , puede utilizar la siguiente configuración:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "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"
      }
    }
  }
}

Localice la entrada de comando para uv y reemplácela con la ruta absoluta del ejecutable uv . Esto garantiza que se use la versión correcta de uv al iniciar el servidor. En una Mac, puede encontrar esta ruta usando which uv .
Reinicie Claude Desktop para aplicar los cambios.

Desarrollo

En el directorio de test-services ejecute docker compose up -d para iniciar el clúster ClickHouse.
Agregue las siguientes variables a un archivo .env en la raíz del repositorio.

Nota: El uso del usuario default en este contexto está destinado únicamente a fines de desarrollo local.

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

Ejecute uv sync para instalar las dependencias. Para instalar uv , siga las instrucciones aquí . Luego, ejecute source .venv/bin/activate .
Para realizar pruebas fácilmente, puede ejecutar mcp dev mcp_clickhouse/mcp_server.py para iniciar el servidor MCP.

Variables de entorno

Las siguientes variables de entorno se utilizan para configurar la conexión de ClickHouse:

Variables requeridas

CLICKHOUSE_HOST : El nombre de host de su servidor ClickHouse
CLICKHOUSE_USER : El nombre de usuario para la autenticación
CLICKHOUSE_PASSWORD : La contraseña para la autenticación

[!PRECAUCIÓN]
Es importante tratar a su usuario de base de datos MCP como a cualquier cliente externo que se conecte a ella, otorgándole únicamente los privilegios mínimos necesarios para su funcionamiento. Se debe evitar estrictamente el uso de usuarios predeterminados o administrativos.

Variables opcionales

CLICKHOUSE_PORT : El número de puerto de su servidor ClickHouse
- Predeterminado: 8443 si HTTPS está habilitado, 8123 si está deshabilitado
- Generalmente no es necesario configurarlo a menos que se utilice un puerto no estándar
CLICKHOUSE_SECURE : Habilitar/deshabilitar la conexión HTTPS
- Valor predeterminado: "true"
- Establezca en "false" para conexiones no seguras
CLICKHOUSE_VERIFY : Habilitar/deshabilitar la verificación del certificado SSL
- Valor predeterminado: "true"
- Establezca en "false" para deshabilitar la verificación del certificado (no recomendado para producción)
CLICKHOUSE_CONNECT_TIMEOUT : Tiempo de espera de conexión en segundos
- Valor predeterminado: "30"
- Aumente este valor si experimenta tiempos de espera de conexión
CLICKHOUSE_SEND_RECEIVE_TIMEOUT : Tiempo de espera de envío/recepción en segundos
- Valor predeterminado: "300"
- Aumente este valor para consultas de larga duración
CLICKHOUSE_DATABASE : Base de datos predeterminada para utilizar
- Predeterminado: Ninguno (usa el valor predeterminado del servidor)
- Configure esto para conectarse automáticamente a una base de datos específica

Configuraciones de ejemplo

Para el desarrollo local con 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)

Puede configurar estas variables en su entorno, en un archivo .env o en la configuración de Claude Desktop:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>"
      }
    }
  }
}

mcp-clickhouse

Integrations

Servidor MCP de ClickHouse

Características

Herramientas

Configuración

Desarrollo

Variables de entorno

Variables requeridas

Variables opcionales

Configuraciones de ejemplo

Descripción general de YouTube

Tools

Related Resources

Appeared in Searches