Configure o servidor MCP do ClickHouse

O servidor MCP do ClickHouse permite que assistentes de IA compatíveis explorem bancos de dados, inspecionem tabelas e executem consultas SQL no ClickHouse. Este guia configura o servidor stdio local usando o uv e o conecta a um cliente MCP popular.

Por padrão, o servidor permite consultas somente leitura. Use um usuário dedicado do ClickHouse, com apenas as permissões necessárias para o assistente, e não use o usuário default nem um usuário administrativo.

O passo a passo a seguir demonstra a configuração com o Claude Desktop. Os mesmos detalhes de conexão do ClickHouse se aplicam aos outros clientes abordados neste guia.

Pré-requisitos

Antes de começar:

Instale o uv.
Instale o cliente MCP que deseja usar.
Reúna o hostname, o nome de usuário e a senha do seu serviço ClickHouse.

Os exemplos abaixo usam estes valores de marcador:

Variável de ambiente	Valor
`CLICKHOUSE_HOST`	`your-clickhouse-host`
`CLICKHOUSE_USER`	`your-clickhouse-user`
`CLICKHOUSE_PASSWORD`	`your-clickhouse-password`

Substitua-os pelas informações de conexão. Em um serviço ClickHouse Cloud, o servidor usa HTTPS na porta 8443 por padrão. Em um serviço autogerenciado que usa HTTP sem criptografia, defina também CLICKHOUSE_SECURE=false e, se necessário, CLICKHOUSE_PORT=8123.

Configure seu cliente MCP

Execute o seguinte comando no 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

Execute claude mcp list para verificar a conexão ou digite /mcp no Claude Code para inspecionar o servidor e as ferramentas disponíveis.

No Claude Desktop, abra Settings, selecione Developer e clique em Edit config. Adicione o seguinte servidor ao arquivo 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"
      }
    }
  }
}

Salve o arquivo e reinicie o Claude Desktop. Abra Connectors no campo de composição do chat para confirmar que mcp-clickhouse está disponível.

Adicione o servidor usando a CLI do 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

Execute codex mcp list para verificar a conexão ou digite /mcp na interface de terminal do Codex. A CLI do Codex, a extensão do Codex para IDEs e o aplicativo de desktop do ChatGPT compartilham a configuração do MCP em ~/.codex/config.toml.

O aplicativo de desktop do ChatGPT configura servidores MCP locais para o host Codex. Essa configuração é compartilhada com o Codex CLI e a extensão do Codex para IDE.

No aplicativo de desktop do ChatGPT:

Abra Settings e selecione MCP servers.
Selecione Add server e escolha STDIO.
Insira mcp-clickhouse como nome e uv como comando.
Adicione run, --with, mcp-clickhouse, --python, 3.10 e mcp-clickhouse como argumentos, nessa ordem.
Adicione CLICKHOUSE_HOST, CLICKHOUSE_USER e CLICKHOUSE_PASSWORD com os detalhes da sua conexão.
Salve o servidor e reinicie o aplicativo.

Após reiniciar o aplicativo, abra o Codex e insira /mcp no composer para verificar o servidor conectado.

Adicione o seguinte servidor ao arquivo .cursor/mcp.json do projeto atual ou à configuração global do Cursor MCP:

{
  "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"
      }
    }
  }
}

Reinicie o Cursor e abra as configurações de MCP para confirmar que o servidor está ativado.

Adicione o seguinte 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"
      }
    }
  }
}

Reinicie o Windsurf e abra as configurações de MCP para confirmar que o servidor está habilitado.

Verifique a conexão

Depois que o cliente informar que mcp-clickhouse está conectado, peça:

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

O cliente pode pedir que você aprove as primeiras chamadas de ferramenta. Revise cada solicitação antes de conceder acesso.

Solução de problemas

Se o cliente informar que não consegue localizar uv, substitua uv no comando ou na configuração pelo caminho absoluto. Execute which uv no macOS ou Linux, ou where uv no Windows, para encontrar esse caminho.

Para obter configurações adicionais de conexão, suporte opcional ao chDB, transporte HTTP e autenticação, consulte o README do mcp-clickhouse.