Install & Compatibility
Where this runs
tested against v0.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 17.05s
py 3.11
✕ build_error
✓ 16.4s
py 3.12
✕ build_error
✓ 13.2s
py 3.13
✕ build_error
✓ 13.35s
py 3.9
✕ build_error
✕ build_error
161MB installed
● package 161MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
app
✓ from mcp_clickhouse.server.main import app
This quickstart demonstrates how to programmatically run the MCP ClickHouse server using uvicorn. Note that `MCP_CLICKHOUSE_DB_URL` must be set for the server to function correctly. After running, you can access the API at `http://localhost:8000` (e.g., `http://localhost:8000/health`). For typical use, the CLI command `mcp-clickhouse start` is also available after installation.
import uvicorn
import os
from mcp_clickhouse.server.main import app
# Set required environment variables for ClickHouse connection
# In a real scenario, you would provide actual credentials or use a .env file.
os.environ['MCP_CLICKHOUSE_DB_URL'] = os.environ.get('MCP_CLICKHOUSE_DB_URL', 'clickhouse://user:password@localhost:8123/default')
if __name__ == "__main__":
print(f"Starting MCP ClickHouse server on http://0.0.0.0:8000")
print(f"Using ClickHouse DB URL: {os.environ['MCP_CLICKHOUSE_DB_URL']}")
uvicorn.run(app, host="0.0.0.0", port=8000)
mcp-clickhouse --version
Debug
Known issues
breakingAs a pre-1.0.0 library, internal APIs and configuration options may change between minor versions (e.g., 0.x.y to 0.x+1.z) without explicit breaking change notices. Always refer to the latest source for API stability.fixConsult the `pyproject.toml` for up-to-date dependencies and `mcp_clickhouse/server/settings.py` for current environment variable configuration keys when upgrading minor versions.
affects: All versions < 1.0.0
gotchaThe MCP ClickHouse server requires an external ClickHouse database instance to connect to. It does not embed or manage a ClickHouse server itself.fixEnsure a running ClickHouse instance is accessible from where `mcp-clickhouse` is deployed, and that its connection details are correctly configured via the `MCP_CLICKHOUSE_DB_URL` environment variable.
affects: All versions
gotchaConfiguration for the server, including database connection details and other settings, is primarily managed through environment variables (e.g., `MCP_CLICKHOUSE_DB_URL`), following Pydantic Settings conventions. There is no traditional configuration file.fixSet all required `MCP_CLICKHOUSE_` prefixed environment variables in your deployment environment or provide them via a `.env` file loaded at application startup.
affects: All versions
Upgrade
Version history
0.4.0latest on PyPI · released Jun 3, 2026
Audit
Dependencies
fastapirequiredCore web framework for the API server.
uvicornrequiredASGI server to run the FastAPI application.
asyncio_mqttrequiredFor MQTT client integration.
clickhouse-connectrequiredClient library for interacting with ClickHouse database.
pydanticrequiredFor data validation and managing server settings from environment variables.
python-dotenvrequiredFor loading environment variables from .env files.
python-json-loggerrequiredFor structured JSON logging.
python-joserequiredFor JSON Web Token (JWT) handling and authentication.
typerrequiredFor building the command-line interface (CLI) to run the server.