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)
This is the beginning of the README. Read the rest at the original. Read the full README ↗
