mcp-clickhouse
An MCP server for ClickHouse.
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- 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).
- Low install friction; pure Python wheel with five runtime dependencies.
License · maintenance · safety
Apache-2.0 (permissive) — Apache-2.0 permissive license allows commercial and private use without restriction.
last release 2026-07-17 (28 days) · last repo commit 2026-08-05 · 851 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 160,029 downloads/mo, #10,678 on PyPI
Alternatives
Verify before relying
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- 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.
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 on it.
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
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.
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).
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-clickhouseVerify 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
| License | Apache-2.0 permissive |
| Python support | Supports the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 5 packagescachetoolsclickhouse-connectfastmcppython-dotenvtruststore |
| Maintenance | Actively maintained 28 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 160,029 / month, #10,678 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
Evidence: mcp_clickhouse-0.4.1-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “clickhouse mcp server”
- mcp-clickhouseAn MCP server that exposes ClickHouse database operations—query…
- mcp-grafanaAn MCP server that exposes Grafana dashboards, datasources, and query…
- chdbchDB is an in-process SQL OLAP engine powered by ClickHouse that…
Give your agent the search over MCP, or paste the wish link into any chat.
More Database packages
psycopg2-binary is a PostgreSQL database adapter for Python that implements the DB API 2.0 specification, enabling Python applications to connect to and query PostgreSQL databases with thread-safe concurrent operations.
Python client library for connecting to and executing commands against Redis key-value stores, supporting both synchronous and asynchronous operations.
Install it if your application needs to interact with Redis; the only prerequisite is a running Redis server instance.
YDB Python SDK is the official client library for connecting to and querying YDB databases from Python applications.
Install it if you need to connect Python applications to YDB databases.
Connects Python applications to Snowflake data warehouses using the DB API 2.0 specification, enabling SQL queries, data transfers, and warehouse operations.
sqlparse tokenizes SQL text into a tree of statements, clauses, and expressions, and provides functions to split scripts, format queries, and inspect parsed tokens without validating dialect or syntax.
Install it if you need to manipulate, format, or analyze SQL text programmatically.
Provides base adapter protocols and shared functionality that database adapters use to integrate with dbt-core, handling connections, dialect translation, relation caching, and core interface management.
See also chdb · clickhouse-connect · chdb-core · postgres-mcp · excel-mcp-server · mcp-server-odoo · airflow-clickhouse-plugin · astro-airflow-mcp · tilt-mcp · logtail-python