# ClickHouse

This MCP server connects Claude Code to ClickHouse clusters and chDB for SQL queries, database discovery, and table browsing.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 892
- Author: ClickHouse
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ClickHouse/mcp-clickhouse
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/clickhouse

## What it does

ClickHouse exposes tools for working with data: `run_query` executes SQL, `list_databases` returns databases, and `list_tables` browses tables with pagination. Table lookup can filter names and include column details. Queries use read-only mode by default.

Values can be sent separately through `params` and ClickHouse placeholders such as `{name:Type}`. The `run_query` tool also accepts `DESCRIBE` for inspecting result columns and `EXPLAIN ESTIMATE` for estimating reads. The connection needs `CLICKHOUSE_HOST`, `CLICKHOUSE_USER`, and `CLICKHOUSE_PASSWORD`; port and secure transport use separate environment variables.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `CLICKHOUSE_HOST`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`, `CLICKHOUSE_PORT`, `CLICKHOUSE_SECURE`, `CLICKHOUSE_VERIFY`, `CLICKHOUSE_CA_CERT`, `CLICKHOUSE_CLIENT_CERT`, `CLICKHOUSE_CLIENT_CERT_KEY`, `CLICKHOUSE_TLS_MODE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env CLICKHOUSE_HOST=<CLICKHOUSE_HOST> --env CLICKHOUSE_USER=<CLICKHOUSE_USER> --env CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> --env CLICKHOUSE_PORT=<CLICKHOUSE_PORT> --env CLICKHOUSE_SECURE=<CLICKHOUSE_SECURE> --transport stdio clickhouse -- uvx mcp-clickhouse
```
Replace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>

### Codex

**Platform CLI**
```bash
codex mcp add clickhouse --env CLICKHOUSE_HOST=<CLICKHOUSE_HOST> --env CLICKHOUSE_USER=<CLICKHOUSE_USER> --env CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> --env CLICKHOUSE_PORT=<CLICKHOUSE_PORT> --env CLICKHOUSE_SECURE=<CLICKHOUSE_SECURE> -- uvx mcp-clickhouse
```
Replace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "clickhouse": {
            "command": "uvx",
            "args": [
                "mcp-clickhouse"
            ],
            "env": {
                "CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
                "CLICKHOUSE_USER": "<CLICKHOUSE_USER>",
                "CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>",
                "CLICKHOUSE_PORT": "<CLICKHOUSE_PORT>",
                "CLICKHOUSE_SECURE": "<CLICKHOUSE_SECURE>"
            }
        }
    }
}
```
Replace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "clickhouse": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "mcp-clickhouse"
            ],
            "env": {
                "CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
                "CLICKHOUSE_USER": "<CLICKHOUSE_USER>",
                "CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>",
                "CLICKHOUSE_PORT": "<CLICKHOUSE_PORT>",
                "CLICKHOUSE_SECURE": "<CLICKHOUSE_SECURE>"
            }
        }
    }
}
```
Replace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e CLICKHOUSE_HOST=<CLICKHOUSE_HOST> -e CLICKHOUSE_USER=<CLICKHOUSE_USER> -e CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> -e CLICKHOUSE_PORT=<CLICKHOUSE_PORT> -e CLICKHOUSE_SECURE=<CLICKHOUSE_SECURE> clickhouse uvx mcp-clickhouse
```
Replace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>

## When to use it
- run SQL queries against a ClickHouse cluster
- browse ClickHouse databases and tables
- bind values to parameterized SQL queries
- inspect result columns before execution
- estimate reads for a SELECT query

## Example prompts
- Run a ClickHouse query that groups sales from `events` by day.
- List the ClickHouse databases and then show tables matching `orders`.
- Use `DESCRIBE` to inspect this query’s result columns, then run `EXPLAIN ESTIMATE` for its read estimate.

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27669
- [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49845

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md