> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure o servidor MCP do ClickHouse
> Conecte o servidor MCP do ClickHouse ao Claude Code, Claude Desktop, Codex, ChatGPT, Cursor ou Windsurf.
O [servidor MCP do ClickHouse](https://github.com/ClickHouse/mcp-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:
1. [Instale o `uv`](https://docs.astral.sh/uv/getting-started/installation/).
2. Instale o cliente MCP que deseja usar.
3. 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:
```bash theme={null}
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`:
```json theme={null}
{
"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:
```bash theme={null}
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:
1. Abra **Settings** e selecione **MCP servers**.
2. Selecione **Add server** e escolha **STDIO**.
3. Insira `mcp-clickhouse` como nome e `uv` como comando.
4. Adicione `run`, `--with`, `mcp-clickhouse`, `--python`, `3.10` e `mcp-clickhouse` como argumentos, nessa ordem.
5. Adicione `CLICKHOUSE_HOST`, `CLICKHOUSE_USER` e `CLICKHOUSE_PASSWORD` com os detalhes da sua conexão.
6. 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.
Estas etapas configuram um servidor `stdio` local para o Codex no aplicativo de desktop do ChatGPT.
Já o ChatGPT na web usa ferramentas remotas baseadas em MCP fornecidas por plugins.
Para usar ferramentas do ClickHouse no ChatGPT na web, consulte [Remote MCP server no ClickHouse Cloud](/pt-BR/products/cloud/features/ai-ml/remote-mcp).
Adicione o seguinte servidor ao arquivo `.cursor/mcp.json` do projeto atual ou à configuração global do Cursor MCP:
```json theme={null}
{
"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`:
```json theme={null}
{
"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:
```text theme={null}
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`](https://github.com/ClickHouse/mcp-clickhouse).