mcp-clickhouse

What it is and what it does

mcp-clickhouse is an MCP (Model Context Protocol) server that bridges AI assistants and MCP clients to ClickHouse databases. It exposes three main tool categories: ClickHouse tools for executing SQL queries (read-only by default), listing databases, and paginating through tables with optional filtering; chDB tools for running embedded SQL queries directly on files and URLs; and a health check endpoint for orchestrator probes. The server communicates via stdio by default (no auth required) or HTTP/SSE with configurable bearer-token, OAuth/OIDC, or disabled authentication.

The package is designed for integration with Claude Desktop and other MCP-compatible clients. It handles connection pooling via clickhouse-connect, caches responses with cachetools, and manages environment configuration through python-dotenv. Query execution defaults to read-only mode to prevent accidental writes, though write access can be explicitly enabled. The health endpoint returns minimal responses to avoid leaking backend details, with debugging delegated to server logs.

Use it for:

• Enable Claude or other AI assistants to query ClickHouse clusters interactively without direct database access.
• Build MCP-compatible tools that list and explore ClickHouse schemas, databases, and tables with pagination.
• Execute ad-hoc SQL queries against ClickHouse from AI-driven workflows while enforcing read-only mode by default.
• Query data directly from files and URLs using chDB's embedded engine without ETL pipelines.
• Deploy a health-check endpoint for Kubernetes liveness/readiness probes or load balancer monitoring.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

An MCP server that exposes ClickHouse database operations—query execution, database and table listing—as tools for AI assistants and MCP clients, with optional embedded chDB support.

Yes. The package is actively maintained, has low install friction, carries no known vulnerabilities, and solves a specific problem—exposing ClickHouse as an MCP tool for AI assistants. Install it if you need Claude or another MCP client to query ClickHouse databases. Ensure Python 3.10+ is available and configure authentication before exposing the server over HTTP/SSE.

Install

mcp-clickhouse on PyPI

pip install mcp-clickhouse

uv add mcp-clickhouse

poetry add mcp-clickhouse

Installing mcp-clickhouse

Before you install

Low install friction; pure Python wheel with five runtime dependencies. Actively maintained with recent releases and 851 repository stars. Requires Python 3.10 or later.

License in practice

Apache-2.0 permissive license allows commercial and private use without restriction.

Quickstart

pip install mcp-clickhouse

# Set environment variables
export CLICKHOUSE_HOST="your-host"
export CLICKHOUSE_USER="your-user"
export CLICKHOUSE_PASSWORD="your-password"

# Run the server
mcp-clickhouse

# Or with chDB support:
pip install 'mcp-clickhouse[chdb]'
export CHDB_ENABLED="true"
mcp-clickhouse

Requires Python 3.10 or later. For HTTP/SSE transport, authentication must be configured via CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED (development only).

Verify before relying

• Whether chDB queries can access remote data sources (files, URLs, databases) without additional setup beyond the optional chdb extra.
• Performance characteristics when listing tables with large page sizes or detailed column metadata enabled.
• Specific ClickHouse cluster versions and configurations tested or supported.

Package facts

Evidence: mcp_clickhouse-0.4.1-py3-none-any.whl

Tags

More Database packages