ClickHouse

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 ( ) 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.

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 ( ) 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 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

GET and HEAD requests to the endpoint are intentionally unauthenticated and exempt from Host and Origin validation so orchestrator probes (e.g. Kubernetes liveness/readiness, load balancers) can use runtime-assigned pod or target IPs without extra configuration. /health is reserved and cannot be used as the MCP transport path. The response body is deliberately minimal to avoid leaking backend version strings or error details; debug failures via the server logs.

Example:

curl http://localhost:8000/health

Response: OK

Security

Authentication for HTTP/SSE Transports

When using HTTP or SSE transport, authentication is required by default. The stdio transport (default) does not require authentication as it only communicates via standard input/output.

Three authentication modes are supported. Pick one:

Startup fails if none of these are configured for HTTP/SSE transports.

Setting Up Authentication

1. Generate a secure token (can be any random string):

   # Using uuidgen (macOS/Linux)

uuidgen

Using openssl

openssl rand -hex 32

1. Configure the server with the token:

   export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

1. Configure your MCP client to include the token in requests:

For Claude Desktop with HTTP/SSE transport:

   {

"mcpServers": { "mcp-clickhouse": { "url": "http://127.0.0.1:8000", "headers": { "Authorization": "Bearer your-generated-token" } } } }

Note: the /health endpoint is intentionally unauthenticated (see Health Check Endpoint above). To verify that bearer-token auth is actually rejecting unauthenticated requests, hit the MCP endpoint itself e.g. with the MCP Inspector, or by POSTing a JSON-RPC request to /mcp with and without the Authorization header and confirming the unauthenticated call returns 401.

OAuth / OIDC via FastMCP

For production deployments with identity providers (Azure Entra, Google, GitHub, WorkOS, etc.), delegate authentication to FastMCP's built-in auth providers instead of using a static token. Set FASTMCP_SERVER_AUTH to the full class path