Configurar el servidor MCP de ClickHouse

El servidor MCP de ClickHouse permite a los asistentes de IA compatibles explorar bases de datos, inspeccionar tablas y ejecutar consultas SQL en ClickHouse. Esta guía configura el servidor stdio local con uv y lo conecta a un Client MCP popular.

De forma predeterminada, el servidor solo permite consultas de lectura. Use un usuario de ClickHouse específico con únicamente los permisos que necesite el asistente; no use un usuario predeterminado ni administrativo.

El siguiente tutorial muestra la configuración con Claude Desktop. Los mismos datos de conexión de ClickHouse se aplican a los demás clientes que se describen en esta guía.

Requisitos previos

Antes de empezar:

Instale uv.
Instale el Client MCP que desee utilizar.
Obtenga el nombre de host, el nombre de usuario y la contraseña de su servicio de ClickHouse.

En los ejemplos siguientes se utilizan estos valores de marcador de posición:

Variable de entorno	Valor
`CLICKHOUSE_HOST`	`your-clickhouse-host`
`CLICKHOUSE_USER`	`your-clickhouse-user`
`CLICKHOUSE_PASSWORD`	`your-clickhouse-password`

Sustitúyalos por los datos de conexión correspondientes. En un servicio de ClickHouse Cloud, el servidor utiliza HTTPS en el puerto 8443 de forma predeterminada. Para un servicio autogestionado que use HTTP sin cifrar, configure también CLICKHOUSE_SECURE=false y, si es necesario, CLICKHOUSE_PORT=8123.

Configura tu MCP Client

Ejecute el siguiente comando en la terminal:

claude mcp add \
  --transport stdio \
  --env CLICKHOUSE_HOST=your-clickhouse-host \
  --env CLICKHOUSE_USER=your-clickhouse-user \
  --env CLICKHOUSE_PASSWORD=your-clickhouse-password \
  --scope user \
  mcp-clickhouse -- \
  uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

Ejecute claude mcp list para verificar la conexión o escriba /mcp en Claude Code para inspeccionar el servidor y sus herramientas.

En Claude Desktop, abre Settings, selecciona Developer y, a continuación, Edit config. Añade el siguiente servidor a claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_USER": "your-clickhouse-user",
        "CLICKHOUSE_PASSWORD": "your-clickhouse-password"
      }
    }
  }
}

Guarda el archivo y reinicia Claude Desktop. Abre Connectors en el área de redacción del chat para confirmar que mcp-clickhouse está disponible.

Agrega el servidor desde la CLI de Codex:

codex mcp add mcp-clickhouse \
  --env CLICKHOUSE_HOST=your-clickhouse-host \
  --env CLICKHOUSE_USER=your-clickhouse-user \
  --env CLICKHOUSE_PASSWORD=your-clickhouse-password \
  -- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

Ejecuta codex mcp list para verificar la conexión o escribe /mcp en la interfaz de terminal de Codex. La CLI de Codex, la extensión de Codex para IDE y la aplicación de escritorio de ChatGPT comparten la configuración de MCP en ~/.codex/config.toml.

La aplicación de escritorio de ChatGPT configura servidores MCP locales para su host de Codex. Esta configuración se comparte con Codex CLI y la extensión de Codex para IDE.

En la aplicación de escritorio de ChatGPT:

Abra Configuración y seleccione Servidores MCP.
Seleccione Añadir servidor y elija STDIO.
Introduzca mcp-clickhouse como nombre y uv como comando.
Añada run, --with, mcp-clickhouse, --python, 3.10 y mcp-clickhouse como argumentos, en ese orden.
Añada CLICKHOUSE_HOST, CLICKHOUSE_USER y CLICKHOUSE_PASSWORD con los datos de conexión.
Guarde el servidor y reinicie la aplicación.

Tras reiniciar la aplicación, abra Codex e introduzca /mcp en el campo de redacción para inspeccionar el servidor conectado.

Añade el siguiente servidor a .cursor/mcp.json para el proyecto actual o a la configuración global de MCP de Cursor:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_USER": "your-clickhouse-user",
        "CLICKHOUSE_PASSWORD": "your-clickhouse-password"
      }
    }
  }
}

Reinicia Cursor y abre su configuración de MCP para confirmar que el servidor esté habilitado.

Agrega el siguiente servidor a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_USER": "your-clickhouse-user",
        "CLICKHOUSE_PASSWORD": "your-clickhouse-password"
      }
    }
  }
}

Recarga Windsurf y, a continuación, abre la configuración de MCP para confirmar que el servidor está habilitado.

Verifique la conexión

Cuando el Client indique que mcp-clickhouse está conectado, pídale lo siguiente:

List the databases available in ClickHouse, then show me the tables in one of them.

Es posible que el Client te pida aprobar las primeras llamadas a herramientas. Revisa cada solicitud antes de conceder acceso.

Solución de problemas

Si el Client informa de que no puede encontrar uv, sustituya uv en el comando o la configuración por su ruta absoluta. Ejecute which uv en macOS o Linux, o where uv en Windows, para obtener esa ruta.

Para conocer otras opciones de conexión, la compatibilidad opcional con chDB, el transporte HTTP y la autenticación, consulte el README de mcp-clickhouse.