ClickHouse MCP Server

An MCP server for ClickHouse. The server implements MCP 2026-07-28 and supports legacy initialize handshakes from 2024-11-05 through 2025-11-25. Modern clients use sessionless requests and server/discover. Existing clients can continue to negotiate the legacy protocol. It runs locally over stdio via the published package.

People who work with Clickhouse and Chdb and want it reachable from Claude, Cursor, VS Code, or another MCP client. The project is written in Python.

VERIFIED ACTIVE

LAST COMMIT 2026-09-16 · ★ 876 · #5 OF 168 MAINTAINED DATABASE · VERIFIED 2026-09-18

Apache-2.0 · Python servers · how we verify → /methodology

01 · Install ClickHouse

before you install - you'll need

Set CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_ROLE, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, CLICKHOUSE_CONNECT_TIMEOUT, CHDB_ENABLED, CLICKHOUSE_ENABLED, CHDB_DATA_PATH, CLICKHOUSE_ALLOW_WRITE_ACCESS before connecting. CLICKHOUSE_USER, CLICKHOUSE_PASSWORD are optional or environment-specific per the README.

Claude Code

claude mcp add clickhouse-mcp-clickhouse -- uvx mcp-clickhouse

Claude Desktop / Cursor / VS Code - add to config

{
  "mcpServers": {
    "clickhouse-mcp-clickhouse": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ]
    }
  }
}

Same JSON for Cursor. For VS Code, rename the top-level key from `mcpServers` to `servers`.

Using another client? Same JSON, different key

Claude Desktop · mcpServers

Cursor · mcpServers

VS Code · servers

Windsurf · mcpServers

Zed · context_servers

Cline · mcpServers

Roo Code · mcpServers

Continue · mcpServers

LibreChat · mcpServers

Gemini CLI · mcpServers

Codex CLI · mcp_servers

Full setup guides: every client.

02 · Evidence

Security posture

What to check before giving this server access to your agent - from the registry, GitHub, and our own probes. We don't score safety; we show what's verifiable.

runs as local process (stdio) - runs on your machine with your user's permissions · container (OCI image) - can be sandboxed away from your filesystem

license Apache-2.0 - declared in the repository

pypi package mcp-clickhouse - check the name against the project README before installing (PyPI has no namespace ownership)

registry namespace io.github.ClickHouse is GitHub-verified and matches the repo owner

03 · What ClickHouse can do

Prose above is summarized from the project's README and registry record - no invented capabilities.

Latest releases

v0.6.0 · 2026-09-03

mcp-clickhouse v0.6.0 · This release moves mcp-clickhouse to FastMCP 4 and adds MCP 2026-07-28 support while preserving legacy MCP clients and the standalone HTTP+SSE transport. · Before upgrading · Custom middleware…

v0.5.0 · 2026-09-01

mcp-clickhouse v0.5.0 · This release improves HTTP transport security, query execution reliability, multi-user request isolation, and result handling. It includes breaking HTTP/SSE configuration changes. · Before…

v0.4.1 · 2026-07-17

v0.4.1 · Advertise official ClickHouse Agent Skills to agents via FastMCP server-level instructions, replacing the previous tool-based advisory guidance. (#193) · Publish mcp-clickhouse to the official MCP Registry…

04 · Who maintains ClickHouse

ClickHouse is maintained by clickhouse. It's the only MCP server we track from this author; the repo dates to Dec 2024.

05 · Facts

repository: github.com/clickhouse/mcp-clickhouse
website: https://clickhouse.com/
category: database - ranked #5 of 168 actively-maintained database servers as of 2026-09-18.
release cadence: 3 releases in the last 90 days (latest 2026-09-03)
registry: io.github.ClickHouse/mcp-clickhouse (active, first published 2026-07-17 · 3 versions)
packages: pypi:mcp-clickhouse · oci:ghcr.io/clickhouse/mcp-clickhouse:0.6.0

06 · ClickHouse FAQ

What is ClickHouse?

Is ClickHouse still maintained?

Yes - as of 2026-09-18, its last commit was 2026-09-16 and it shipped 3 releases in the last 90 days. We re-verify nightly.

How do I install ClickHouse?

Run `uvx mcp-clickhouse`. The README documents 12 environment variables (CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER…) to set first. Set CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_ROLE, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, CLICKHOUSE_CONNECT_TIMEOUT, CHDB_ENABLED, CLICKHOUSE_ENABLED, CHDB_DATA_PATH, CLICKHOUSE_ALLOW_WRITE_ACCESS before connecting. CLICKHOUSE_USER, CLICKHOUSE_PASSWORD are optional or environment-specific per the README. You can also paste the ready-made client config above.

Does ClickHouse run locally?

Yes - it's a stdio server: it runs on your machine (via uvx) with your user's permissions. Your data stays local unless the server itself calls external APIs.

07 · Alternatives to ClickHouse

Alternatives to ClickHouse

Maintained database servers if ClickHouse isn't the fit.

Pairs well with

Servers that cover what ClickHouse doesn't - only shown when the pairing reason fits the companion.

More database MCP servers · Database MCP · Codegraph · Colabfit MCP · Zotero Bridge · Server Couchbase

More Python MCP servers · MetricHub Quant - A股量化数据 · Cpersona · Math MCP Learning · Clueso · Clipboard · see all