ClickHouse

Servidor MCP de Clickhouse

Un proyecto de servidor MCP para la base de datos Clickhouse.

Instalación

Puedes instalar el paquete usando uv:

uv pip install clickhouse-mcp-server

O usando pip:

pip install clickhouse-mcp-server

Componentes

Herramientas

El servidor proporciona dos herramientas:

• connect_database: Se conecta a una base de datos Clickhouse específica

  • Parámetro database: Nombre de la base de datos a la que conectarse (cadena)
  • Devuelve un mensaje de confirmación cuando la conexión es exitosa

• execute_query: Ejecuta consultas de Clickhouse

  • Parámetro query: Consulta(s) SQL a ejecutar (cadena)
  • Devuelve los resultados de la consulta en formato JSON
  • Se pueden enviar múltiples consultas separadas por punto y coma

Configuración

El servidor utiliza las siguientes variables de entorno:

• CLICKHOUSE_HOST: Dirección del servidor Clickhouse (predeterminado: "localhost")
• CLICKHOUSE_USER: Nombre de usuario de Clickhouse (predeterminado: "root")
• CLICKHOUSE_PASSWORD: Contraseña de Clickhouse (predeterminado: "")
• CLICKHOUSE_DATABASE: Base de datos inicial (opcional)
• CLICKHOUSE_READONLY: Modo de solo lectura (establecer en 1/true para habilitar, predeterminado: false)

Inicio rápido

Instalación

Claude Desktop

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/burakdirin/Projects/clickhouse-mcp-server",
        "run",
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uvx",
      "args": [
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

Instalación mediante Smithery

Para instalar automáticamente el Servidor de Integración de Base de Datos Clickhouse para Claude Desktop a través de Smithery:

npx -y @smithery/cli install @burakdirin/clickhouse-mcp-server --client claude

Desarrollo

Compilación y publicación

Para preparar el paquete para su distribución:

1. Sincronizar dependencias y actualizar el archivo de bloqueo:

uv sync

2. Compilar las distribuciones del paquete:

uv build

Esto creará distribuciones de código fuente y wheel en el directorio dist/.

3. Publicar en PyPI:

uv publish

Nota: Necesitarás configurar las credenciales de PyPI mediante variables de entorno o banderas de comando:

• Token: --token o UV_PUBLISH_TOKEN
• O nombre de usuario/contraseña: --username/UV_PUBLISH_USERNAME y --password/UV_PUBLISH_PASSWORD

Depuración

Dado que los servidores MCP se ejecutan sobre stdio, la depuración puede ser desafiante. Para la mejor experiencia de depuración, recomendamos encarecidamente usar el Inspector MCP.

Puedes lanzar el Inspector MCP a través de npm con este comando:

npx @modelcontextprotocol/inspector uv --directory /Users/burakdirin/Projects/clickhouse-mcp-server run clickhouse-mcp-server

Al lanzarlo, el Inspector mostrará una URL que puedes acceder en tu navegador para comenzar a depurar.