ClickHouse MCP Server

An MCP server for ClickHouse.

The server implements MCP 2026-07-28 and supports legacy initialize handshakes from 2024-11-05 through 2025-11-25. Modern clients use sessionless requests and server/discover. Existing clients can continue to negotiate the legacy protocol.

[!NOTE] HTTP requests without MCP-Protocol-Version are routed through legacy handling so clients from before 2025-06-18 can continue to connect. MCP 2026-07-28 permits this behavior on servers that support those clients. Modern clients should send the header on every POST request.

Features

ClickHouse Tools

ClickHouse tool responses are JSON-encoded strings. Integers outside [-9007199254740991, 9007199254740991] are returned as decimal strings to preserve exact values in JavaScript clients. This applies to query rows and integer table metadata. Safe-range integers and booleans keep their JSON types.

• run_query
• Execute SQL queries on your ClickHouse cluster.
• Input: query (string): The SQL query to execute.
• Optional input: params (object): Named values for ClickHouse {name:Type} placeholders. See Query parameters.
• Queries run in read-only mode by default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), but writes can be enabled explicitly if needed.
• DESCRIBE (<query>) and EXPLAIN ESTIMATE <query> run here too and are optional ways to inspect a query's result schema or its estimated reads. See Checking a query before running it.

• list_databases
• List all databases on your ClickHouse cluster.

• list_tables
• List tables in a database with pagination.
• Required input: database (string).
• Optional inputs:
• like / not_like (string): Apply LIKE or NOT LIKE filters to table names.
• page_token (string): Single-use token returned by a previous call. It is retained for up to one hour.
• page_size (int, default 50): Number of tables returned per page; must be greater than 0.
• include_detailed_columns (bool, default true): When false, omits column metadata for lighter responses while keeping the full create_table_query.
• Response shape:
• tables: Array of table objects for the current page.
• next_page_token: Pass this single-use value back before it expires to fetch the next page, or null when there are no more tables.
• total_tables: Total count of tables that match the supplied filters.

#### Agents Schema discovery

The server instructions suggest reading Agents Schema's canonical AGENTS.ROOT through run_query when list_databases reveals an AGENTS database, before writing analytical SQL. This is guidance for the agent: no metadata is fetched automatically, tool results are unchanged, and existing ClickHouse permissions still apply. If AGENTS.ROOT is missing or inaccessible, normal discovery and queries remain available.

#### Query parameters

Pass values separately from SQL through the optional params object:

{
  "query": "SELECT {id:UInt32} AS id, {name:String} AS name",
  "params": {"id": 13, "name": "O'Reilly"}
}

Use ClickHouse's {name:Type} placeholders without quoting them. Keep the opening brace, name, and colon adjacent, as in {id:UInt32}. Spaces after the colon and within the type are supported, as in {id: UInt32} and {amount:Decimal(18, 4)}. For compatibility across supported driver versions, start names with a letter or underscore and use only letters, digits, and underscores. Python-style %s or %(name)s formatting and the driver's $name$ raw binary parameters are not supported. Calls with only query still work. Omitting params, passing null, or passing an empty object leaves the query unbound.

Parameter values can be JSON strings, numbers, booleans, null, or arrays, provided they match the declared ClickHouse type:

• Use null with a Nullable(...) type.
• Pass exact integers outside JavaScript's safe range as decimal strings, for

example "18446744073709551615" with {id:UInt64}. Dates, timestamps, and exact decimals can also be passed as strings with the corresponding ClickHouse type.

• Bind vectors as one array, for example {vector:Array(Float32)} with

"params": {"vector": [0.25, 0.5, 0.75]}.

• Nulls inside arrays depend on the installed driver. They work with

clickhouse-connect 1.8.0 but fail with the supported minimum 1.0.0.

• JSON lists and objects cannot bind to ClickHouse Tuple and Map types.

Missing values and incompatible types return query errors. With non-empty params, a query carrying many unterminated {name: placeholder starts is rejected, including placeholder-like text in comments or string literals. Parameterized queries use the same write protection, timeouts, cancellation, and JSON result encoding as other queries.

Parameter values stay out of the MCP server's normal SQL log messages, but remain in MCP tool arguments and may appear in backend errors. ClickHouse 26.3.20.7 substitutes values into the query text in system.query_log, system.processes, and system.text_log. Parameter binding is not a privacy feature and does not reduce the number of vector values sent in a tool call.

#### Checking a query before running it

run_query also runs DESCRIBE and EXPLAIN ESTIMATE. Both are optional checks: reach for DESCRIBE when you need a query's output columns and types, and for EXPLAIN ESTIMATE before a SELECT that could be expensive.

DESCRIBE (<query>) inspects the result schema and returns the same output-column metadata as DESCRIBE TABLE:

DESCRIBE (SELECT user, sum(amt) FROM events WHERE ts > now() - INTERVAL 30 DAY GROUP BY user)

user      String
sum(amt)  Decimal(38, 2)

ClickHouse has to analyze the query to answer, so analysis errors surface here, with ClickHouse's own message, instead of part way through execution:

DESCRIBE (SELECT usr FROM events)  -> Code: 47. Unknown expression identifier `usr` ... Maybe you meant: ['user']
DESCRIBE (SELECT * FROM nosuch)    -> Code: 60. Unknown table expression identifier 'nosuch'

A query that describes cleanly can still fail when it runs, on a memory limit or a remote server error, and it says nothing about cost.

EXPLAIN ESTIMATE <query> returns the parts, rows and marks the query would read, one row per table, which is what separates a primary key lookup from a full scan:

EXPLAIN ESTIMATE SELECT count() FROM events WHERE id = 42

database  table   parts  rows   marks
default   events  1      8192   1

Those are estimated reads from MergeTree family tables, after primary key and partition pruning. They are not run time and not result size, and other table engines are not covered.

Neither statement runs the query body, but analysis is not always free: DESCRIBE (SELECT (SELECT sleep(1))) executes the scalar subquery while analyzing. Both are read-only and work under the default CLICKHOUSE_ALLOW_WRITE_ACCESS=false. See the ClickHouse documentation for EXPLAIN ESTIMATE and DESCRIBE.

chDB Tools

• run_chdb_select_query
• Execute SQL queries using chDB's embedded ClickHouse engine.
• Input: query (string): The SQL query to execute.
• Integers outside [-9007199254740991, 9007199254740991] are returned as decimal strings.
• Query data directly from various sources (files, URLs, databases) without ETL processes.
• Requires the optional chdb extra: pip install 'mcp-clickhouse[chdb]'

Health Check Endpoint

When running with HTTP or SSE transport, a health check endpoint is available at /health. This endpoint:

• Returns 200 OK (body: OK) if the server is healthy and can connect to ClickHouse
• Returns 503 Service Unavailable with a generic error message if the server cannot connect to ClickHouse
• Returns 503 if a ClickHouse probe does not finish within two seconds. Concurrent requests share one in-flight probe
• Reuses a completed probe result for one second, so probes that arrive in quick succession do not each connect to ClickHouse. A failure or a recovery can therefore be reported up to a second late