mcp-clickhouse v0.4.0

This release adds OAuth/OIDC authentication, official GHCR container images, and fixes concurrency and MCP protocol issues. It includes a few behavior changes (see Behavior changes section before upgrading).

Behavior changes

• Auth modes are now mutually exclusive. Static token, FastMCP OAuth, and disabled mode can no longer be combined — configure exactly one. If you currently set more than one, pick a single mode.
• /health is now unauthenticated in all modes (previously gated under static-token mode). Response bodies are trimmed to OK / a generic error string and no longer expose ClickHouse version or exception details. Update any monitoring that parsed the old body.
• Tool responses are now JSON-encoded strings rather than raw dicts. This fixes MCP protocol validation errors, but the wire format clients receive has changed.

Added

• OAuth/OIDC auth providers on HTTP/SSE transports via FASTMCP_SERVER_AUTH (Azure Entra, Google, GitHub, WorkOS, etc.). (#173, fixes #171)
• Official multi-arch Docker images on GHCR, published automatically on every release: ghcr.io/clickhouse/mcp-clickhouse:0.4.0, :0.4, and :latest (linux/amd64 + linux/arm64). Swap your image reference from mcp/clickhouse to ghcr.io/clickhouse/mcp-clickhouse:latest — same env-var config, same entrypoint. (#174, #187)

Fixed

• Long-running queries no longer block other tool calls. run_query and run_chdb_select_query now await their thread-pool futures asynchronously, so concurrent calls are served while a slow query is in flight. (#136, fixes #128)
• Tool responses return valid JSON strings, avoiding MCP protocol validation errors on successful queries. (#154)

Docker image

docker pull ghcr.io/clickhouse/mcp-clickhouse:0.4.0

Full changelog: v0.3.0...v0.4.0

What's Changed

• SNI override support via CLICKHOUSE_SNI environment variable for connections behind proxies or load balancers. (#127)
• Lazy-load chdb to avoid ~80-100 MB memory overhead when the feature is disabled. (#144)
• Made chdb an optional dependency for Windows compatibility. (#145)
• Optional write access mode via CLICKHOUSE_WRITE_ACCESS environment variable, with built-in DROP and TRUNCATE protection. (#93)
• Client config override support through MCP Context session states, enabling dynamic connection switching at runtime. (#115)
• Custom middleware injection via CLICKHOUSE_MCP_MIDDLEWARE environment variable for hooking into the MCP server lifecycle. Includes an example middleware module. (#114)

Full Changelog: v0.2.0...v0.3.0

What's Changed

• Add authentication support for HTTP and SSE transports by @joe-clickhouse in #113

Full Changelog: v0.1.13...v0.2.0

What's Changed

• Syncing GitHub releases with PyPI releases going forward
• See PyPI release history for previous versions

Features in v0.1.13

• Execute SQL queries against ClickHouse clusters with readonly protection
• List databases and tables with pagination, filtering, and detailed metadata
• chDB Support: Query files, URLs, and databases directly using embedded ClickHouse engine (no ETL required)
• Works with ClickHouse Cloud, self-hosted instances, and local development

Full Changelog: https://github.com/ClickHouse/mcp-clickhouse/commits/v0.1.13