MCP Clickhouse

What ClickHouse/mcp-clickhouse MCP server does

ClickHouse/mcp-clickhouse MCP server connects MCP clients to ClickHouse and exposes tools for database discovery, table inspection, and SQL execution. It also provides an optional chDB integration for running queries through chDB's embedded ClickHouse engine.

The ClickHouse tools return JSON-encoded strings. Large integers outside JavaScript's safe integer range are represented as decimal strings, while safe-range integers and booleans retain their normal JSON types.

How it works

The server supports stdio by default and can also run over HTTP or SSE. Stdio communication does not require authentication. HTTP and SSE deployments require authentication unless authentication is explicitly disabled for local development.

ClickHouse queries run with read-only access by default. Write access can be enabled through an environment setting, and destructive operations such as DROP and TRUNCATE require a separate setting. This makes the default configuration suitable for agents that only need to inspect data or execute read queries.

For HTTP and SSE deployments, /health returns 200 OK when the server can connect to ClickHouse. It returns 503 when the connection fails or a probe does not complete within two seconds. The endpoint is unauthenticated and reserved for health checks.

Setup and configuration

The package is published on PyPI as mcp-clickhouse. The optional chDB capability requires the chdb extra. ClickHouse connection and transport configuration must be supplied according to the deployment environment, while HTTP and SSE authentication can use one of these approaches:

• A static bearer token in CLICKHOUSE_MCP_AUTH_TOKEN.
• A FastMCP OAuth or OIDC provider configured through FASTMCP_SERVER_AUTH and provider-specific variables.
• CLICKHOUSE_MCP_AUTH_DISABLED=true for local development.

HTTP and SSE startup fails when none of the authentication options is configured. The health endpoint remains unauthenticated even when MCP requests require a bearer token or OAuth authentication.

Tools and capabilities

ClickHouse/mcp-clickhouse MCP server provides these capabilities:

• list_databases returns the available ClickHouse databases.
• list_tables accepts a database name and can filter table names with LIKE or NOT LIKE patterns.
• list_tables supports pagination with single-use tokens retained for up to one hour. Results include table metadata, matching-table totals, and optionally detailed column information.
• run_query executes SQL against the ClickHouse cluster.
• run_chdb_select_query executes SQL through chDB when the optional dependency is installed. This can query sources such as files, URLs, and databases without an ETL step.

For large schemas, list_tables can omit the detailed columns array while retaining the full create-table query, reducing response size.

Limitations and notes

The server does not provide unrestricted write access by default. Enabling writes changes the permitted operation set, and destructive statements require an additional explicit setting. Agents should therefore be given only the access level appropriate for their task.

Pagination tokens from list_tables are single-use and expire after up to one hour. HTTP health checks do not authenticate and only report a minimal status body; connection failure details must be investigated through server logs.

The available material does not identify a software license or provide a confirmed one-line command for launching the server directly, so installation and licensing details should be verified from the project distribution before automation.