ClickHouse

What ClickHouse MCP server does

The ClickHouse MCP server gives an MCP client a read-only interface to one or more ClickHouse connections. It supports database, table, view, and column discovery; cluster property inspection; parameterized SELECT queries; SHOW statements; and EXPLAIN-style query analysis. The server is intended for agents that need to understand a ClickHouse environment and retrieve data without being allowed to change it.

Connections are organized into profiles. A default profile can be configured with environment variables, while multiple connections can be defined in a user-scoped JSON file. Tools accept a profile name where relevant and otherwise use the default profile.

How it works

The ClickHouse MCP server validates SQL before sending it to ClickHouse. run_query accepts one read-only SELECT or WITH ... SELECT statement and returns either RFC 4180 CSV data with a row count or, when snapshot mode is enabled, a snapshot resource URI and row count. Named parameters can use driver placeholder forms such as %(name)s or {name:Type}.

run_show handles one SHOW introspection statement per call. analyze_query explains a read-only query and can return plan, pipeline, and syntax output; plan and pipeline are the defaults. Metadata tools read information visible to the configured ClickHouse connection, including rows from system.databases, system.tables, and system.columns.

Metadata and cluster information are also available through URI-addressable resources using the chx:// scheme. Snapshot results are exposed as CSV resources, while discovery resources return JSON.

Setup and configuration

The ClickHouse MCP server requires Python 3.13 or newer, a running ClickHouse instance, and a connection DSN. The documented direct runner is uvx mcp-clickhousex.

For a single connection, set MCP_CLICKHOUSE_DSN to a ClickHouse HTTP DSN, for example a URL containing the user, password, host, port, and database. Optional settings control the interactive row limit and timeout, as well as separate limits and timeouts for snapshot queries. Interactive queries default to 500 rows and 30 seconds; snapshot queries default to 10,000 rows and 120 seconds.

Multiple profiles can be configured in ~/.config/mcp-clickhousex/config.json on Unix-like systems or %USERPROFILE%\.config\mcp-clickhousex\config.json on Windows. Profile-specific environment variables use the MCP_CLICKHOUSE_PROFILES_<NAME>_ prefix. URL-reserved characters in credentials must be percent-encoded in the DSN.

Tools and capabilities

• List configured profiles and their descriptions.
• Inspect ClickHouse version and enforced execution limits.
• List visible databases, tables, views, and columns.
• Run parameterized read-only SELECT queries.
• Execute SHOW introspection statements.
• Analyze query plans, pipelines, or syntax.
• Store larger query results as expiring CSV snapshots.

Limitations and notes

Write operations are not supported. DML, DDL, SET, SYSTEM, and similar statements are rejected, and run_show rejects INTO OUTFILE. Interactive query results have a hard ceiling of 1,000 rows, while snapshot results have a hard ceiling of 50,000 rows. Snapshot entries expire after seven days. Query and snapshot limits can be configured but cannot exceed their documented hard ceilings. Results and metadata are limited to what the selected ClickHouse connection can access.