MCP server for running queries and exploring schemas in ClickHouse databases.
MCP server for running queries and exploring schemas in ClickHouse databases.
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.
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 () 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.
• 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.
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.
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"}
} …
MCP server · MCP servers / Databases · Open Source · Apache-2.0 · Python
Website https://github.com/ClickHouse/mcp-clickhouse · Repo https://github.com/ClickHouse/mcp-clickhouse
904 stars · 209 forks · 9 open issues · pushed 2026-11-04 · verified 2026-11-12
Tags: ai-agents, mcp-server, databases
What is ClickHouse MCP Server? ClickHouse MCP Server is a coding tool listed on Scriptiii AI Tools. MCP server for running queries and exploring schemas in ClickHouse databases. Pricing: Free. Free to use. Best for: ai-agents, mcp-server, databases.
Everything you need to know about ClickHouse MCP Server
Similar tools in Coding
Open-source vector database that stores objects and vectors with hybrid search and filtering.
Coding·Free