ClickHouse MCP server

ClickHouse MCP Server

<!-- mcp-name: io.github.ClickHouse/mcp-clickhouse -->

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 (CLICKHOUSEALLOWWRITE_ACCESS=false), but writes can be enabled explicitly if needed.
• DESCRIBE () and EXPLAIN ESTIMATE 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.
• includedetailedcolumns (bool, default true): When false, omits column metadata for lighter responses while keeping the full createtablequery.
• Response shape:
• tables: Array of table objects for the current page.
• nextpagetoken: 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.

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:

Shortened. The full README is on GitHub.