v0.7.0

mcp-clickhouse v0.7.0

This release adds named query parameters and outbound ClickHouse client certificate support, reduces health-check traffic, and reorganizes the server internals.

Before upgrading

• clickhouse-connect 1.x is now required (>=1.0.0,<2). Python 3.10 remains supported.
• Custom middleware must set TLS options such as verify, ca_cert, and client_cert as top-level client overrides. These options are rejected under generic_args and in DSN query parameters. DSNs cannot select chDB.
• A secure override now selects the matching HTTP or HTTPS interface. An explicit interface must agree with it. Use booleans or "true"/"false" for secure and verify. verify also accepts "proxy".
• Some undocumented imports from mcp_clickhouse.mcp_server were removed, including Table, execute_query, and QUERY_EXECUTOR. See the code layout for the owning modules. Public package exports and the documented CLIENT_CONFIG_OVERRIDES_KEY import remain available.

Highlights

• Adds optional params to run_query for ClickHouse {name:Type} binding, including scalar values and arrays. Existing calls continue to work.
• Supports private CA bundles and client certificates for outbound ClickHouse HTTPS connections. Mutual mode authenticates with the certificate, while strict and proxy modes retain Basic authentication.
• Reuses completed /health probe results for one second, reducing repeated database checks. Failure and recovery reporting can lag by up to a second.
• Documents DESCRIBE (<query>) and EXPLAIN ESTIMATE <query> as optional checks through run_query.
• Gives each server assembly its own worker pools and backend state while preserving existing MCP tool and prompt contracts.
• Expands CI coverage to Python 3.10 through 3.14 and uses Python 3.12 in local development examples.

Full Changelog: v0.6.0...v0.7.0

v0.6.0

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 that sets ClickHouse client overrides must await Context.set_state() and use serializable=False.
• The standalone HTTP+SSE transport remains available but is deprecated. Use Streamable HTTP for new deployments.
• Deployments that used FastMCP 2's default OAuth proxy client storage must have clients register and authorize again.
• FastMCP no longer supports Supabase HS256 verification. Use RS256 or ES256.
• Modern HTTP clients should send MCP-Protocol-Version on every POST request.

Highlights

• Supports MCP 2026-07-28 with server/discover, sessionless requests, response caching hints, and request metadata validation.
• Keeps initialize compatibility for MCP 2024-11-05 through 2025-11-25.
• Preserves static token and OAuth authentication, Host and Origin checks, trusted proxy handling, and the minimal unauthenticated /health endpoint.
• Fixes pagination token races and preserves cursors across failures and cancellation.
• Runs metadata work in a separate bounded executor so schema discovery does not delay queries.
• Reports the mcp-clickhouse package version in protocol responses.

Full Changelog: v0.5.0...v0.6.0

v0.5.0

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 upgrading

• HTTP/SSE now validates Host and Origin by default. Wildcard binds require CLICKHOUSE_MCP_ALLOWED_HOSTS.
• Reverse proxies should preserve Host. Otherwise configure CLICKHOUSE_MCP_TRUSTED_PROXIES.
• /health remains unauthenticated and exempt from Host and Origin validation.
• CLICKHOUSE_ALLOW_DROP now also gates destructive DELETE, UPDATE, partition, column, clear, replace, and permanent detach operations.
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT is capped relative to the MCP query timeout unless explicitly configured.

Highlights

• Reuse ClickHouse clients across tool calls and attempt server-side cancellation after query timeouts. (#152)
• Add DNS rebinding protection across HTTP, SSE, fastmcp run, and fastmcp.json. (#226)
• Safely support trusted reverse proxies and X-Forwarded-Host. (#230)
• Preserve request-scoped ClickHouse configuration overrides across executor threads. (#221)
• Expand destructive query protection and avoid false positives inside strings, identifiers, and comments. (#220)
• Return integers outside JavaScript's safe range as decimal strings. (#210)
• Reject invalid list_tables page sizes. (#229)
• Add clearer diagnostics for ClickHouse port and TLS configuration errors. (#212)

This release remains on FastMCP 2 and the MCP 2025-11-25 protocol. FastMCP 4 and MCP 2026-07-28 support are tracked in #218.

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

Full Changelog: v0.4.1...v0.5.0

v0.4.1

v0.4.1

What's Changed

• 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 (registry.modelcontextprotocol.io, synced to github.com/mcp), alongside the existing PyPI and GHCR artifacts. (#206)

Full Changelog: v0.4.0...v0.4.1

v0.4.0

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

v0.3.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

v0.2.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

v0.1.13

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