ClickHouse MCP server

MCP ClickHouse Tool

<!-- mcp-name: io.github.alyiox/mcp-clickhousex -->

A read-only-by-default Model Context Protocol (MCP) server for ClickHouse that provides schema discovery, read-only queries, execution-plan analysis, opt-in writes, and profile-based access to multiple servers from a single toolset deployment.

Read-only is enforced by the engine, not by SQL text matching: every client carries ClickHouse's readonly=1, so writes, external table functions and query-level SETTINGS are refused by the server being queried. There is no write tool to opt into.

Requirements: Python 3.13+, a running ClickHouse instance, and connection details via environment variables or a config file.

Quick start

Set a DSN and run the server with MCP Inspector:

# Option 1: Run directly with uvx (no clone needed)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector@latest uvx mcp-clickhousex

# Option 2: Run from source (clone repo, then)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector@latest uv run mcp-clickhousex

Configuration

A profile is one ClickHouse connection: a DSN plus the row and timeout caps that apply to it. A profile named default always exists; every tool takes an optional profile to reach another, and list_profiles reports what is configured.

Settings come from three sources, merged field by field, later winning:

1. the user-scoped config.json — any number of profiles;
2. MCPCLICKHOUSEPROFILES__ environment variables — any number of profiles;
3. flat MCPCLICKHOUSE environment variables — the default profile only.

Because the merge is per field rather than per profile, a config.json can carry the full set while a flat MCPCLICKHOUSEDSN repoints the default profile at a local server, leaving its other fields intact. With none of the three present, default falls back to http://default:@localhost:8123/default.

Each setting has one field name, spelled three ways — MCPCLICKHOUSE, MCPCLICKHOUSEPROFILES__, or the field lowercased as a JSON key:

Caps are per profile. A value above its ceiling is clamped at startup; a value that is not an integer falls back to the default.

Single connection: flat environment variables are the shortest path.

# Connection DSN.
export MCP_CLICKHOUSE_DSN="http://user:password@host:8123/database"

# Optional description for the default profile (tooling/AI discovery).
export MCP_CLICKHOUSE_DESCRIPTION="Primary cluster"

# Optional caps, defaults shown.
export MCP_CLICKHOUSE_QUERY_MAX_ROWS="500"
export MCP_CLICKHOUSE_QUERY_COMMAND_TIMEOUT_SECONDS="30"
export MCP_CLICKHOUSE_SNAPSHOT_MAX_ROWS="10000"
export MCP_CLICKHOUSE_SNAPSHOT_COMMAND_TIMEOUT_SECONDS="120"

Multiple connections: use the user-scoped config.json, which keeps credentials out of the host's process environment.

• Unix-like: ~/.config/mcp-clickhousex/config.json
• Windows: %USERPROFILE%\.config\mcp-clickhousex\config.json

Shortened. The full README is on GitHub.