Set up the ClickHouse MCP server

The ClickHouse MCP server lets compatible AI assistants explore databases, inspect tables, and run SQL queries against ClickHouse. This guide configures the local stdio server with uv and connects it to a major MCP client.

The server allows read-only queries by default. Use a dedicated ClickHouse user with only the permissions that the assistant needs, and do not use a default or administrative user.

The following walkthrough demonstrates the setup with Claude Desktop. The same ClickHouse connection details apply to the other clients covered in this guide.

Prerequisites

Before you begin:

Install uv.
Install the MCP client that you want to use.
Collect the hostname, username, and password for your ClickHouse service.

The examples below use these placeholder values:

Environment variable	Value
`CLICKHOUSE_HOST`	`your-clickhouse-host`
`CLICKHOUSE_USER`	`your-clickhouse-user`
`CLICKHOUSE_PASSWORD`	`your-clickhouse-password`

Replace them with your connection details. For a ClickHouse Cloud service, the server uses HTTPS on port 8443 by default. For a self-managed service using plain HTTP, also set CLICKHOUSE_SECURE=false and, if needed, CLICKHOUSE_PORT=8123.

Configure your MCP client

Run the following command in your 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

Run claude mcp list to verify the connection, or enter /mcp in Claude Code to inspect the server and its tools.

In Claude Desktop, open Settings, select Developer, and select Edit config. Add the following server to 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"
      }
    }
  }
}

Save the file and restart Claude Desktop. Open Connectors from the chat composer to confirm that mcp-clickhouse is available.

Add the server from the Codex CLI:

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

Run codex mcp list to verify the connection, or enter /mcp in the Codex terminal UI. Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share the MCP configuration in ~/.codex/config.toml.

The ChatGPT desktop app configures local MCP servers for its Codex host. This configuration is shared with Codex CLI and the Codex IDE extension.

In the ChatGPT desktop app:

Open Settings, then select MCP servers.
Select Add server and choose STDIO.
Enter mcp-clickhouse as the name and uv as the command.
Add run, --with, mcp-clickhouse, --python, 3.10, and mcp-clickhouse as arguments, in that order.
Add CLICKHOUSE_HOST, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD with your connection details.
Save the server and restart the app.

After the app restarts, open Codex and enter /mcp in the composer to inspect the connected server.

Add the following server to .cursor/mcp.json for the current project, or to your global Cursor MCP configuration:

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

Reload Cursor, then open its MCP settings to confirm that the server is enabled.

Add the following server to ~/.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"
      }
    }
  }
}

Reload Windsurf, then open its MCP settings to confirm that the server is enabled.

Verify the connection

After the client reports that mcp-clickhouse is connected, ask it:

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

The client might ask you to approve the first tool calls. Review every request before granting access.

Troubleshooting

If the client reports that it cannot find uv, replace uv in the command or configuration with its absolute path. Run which uv on macOS or Linux, or where uv on Windows, to find that path.

For additional connection settings, optional chDB support, HTTP transport, and authentication, see the mcp-clickhouse README.