# ClickHouse [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/alyiox/mcp-clickhousex  
**GitHub Stars:** 0  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/clickhouse

## Description
Read-only MCP server for ClickHouse metadata, parameterized queries, and plan analysis.

## Tools
Capabilities this server exposes over MCP:

- **list_profiles** — List configured connection profiles. Call first when picking a non-default profile.
- **run_query** — Execute read-only `SELECT` (CTEs allowed), one statement per call. Returns rows inline as CSV, or a `chx://snapshots/{id}` URI when `snapshot=true`. Inline limit: 500 rows (hard ceiling 1 000). Snapshot limit: 10 000 rows (hard ceiling 50 000).
- **run_show** — Execute one `SHOW` statement — chiefly `SHOW CREATE TABLE`/`VIEW`/`DICTIONARY` for DDL a listing cannot give you: codecs, TTLs, the full column list. No `INTO OUTFILE`.
- **analyze_query** — EXPLAIN` a read-only `SELECT`; returns plan, pipeline or syntax, no result rows.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "clickhouse": {
    "command": "uvx",
    "args": ["mcp-clickhousex"],
    "env": {
      "MCP_CLICKHOUSE_DSN": ""
    }
  }
}
```

**Requires environment variables:** `MCP_CLICKHOUSE_DSN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What ClickHouse MCP server does

The ClickHouse MCP server gives an MCP client a read-only interface to one or more ClickHouse connections. It supports database, table, view, and column discovery; cluster property inspection; parameterized SELECT queries; SHOW statements; and EXPLAIN-style query analysis. The server is intended for agents that need to understand a ClickHouse environment and retrieve data without being allowed to change it.

Connections are organized into profiles. A default profile can be configured with environment variables, while multiple connections can be defined in a user-scoped JSON file. Tools accept a profile name where relevant and otherwise use the default profile.

## How it works

The ClickHouse MCP server validates SQL before sending it to ClickHouse. `run_query` accepts one read-only `SELECT` or `WITH ... SELECT` statement and returns either RFC 4180 CSV data with a row count or, when snapshot mode is enabled, a snapshot resource URI and row count. Named parameters can use driver placeholder forms such as `%(name)s` or `{name:Type}`.

`run_show` handles one SHOW introspection statement per call. `analyze_query` explains a read-only query and can return plan, pipeline, and syntax output; plan and pipeline are the defaults. Metadata tools read information visible to the configured ClickHouse connection, including rows from `system.databases`, `system.tables`, and `system.columns`.

Metadata and cluster information are also available through URI-addressable resources using the `chx://` scheme. Snapshot results are exposed as CSV resources, while discovery resources return JSON.

## Setup and configuration

The ClickHouse MCP server requires Python 3.13 or newer, a running ClickHouse instance, and a connection DSN. The documented direct runner is `uvx mcp-clickhousex`.

For a single connection, set `MCP_CLICKHOUSE_DSN` to a ClickHouse HTTP DSN, for example a URL containing the user, password, host, port, and database. Optional settings control the interactive row limit and timeout, as well as separate limits and timeouts for snapshot queries. Interactive queries default to 500 rows and 30 seconds; snapshot queries default to 10,000 rows and 120 seconds.

Multiple profiles can be configured in `~/.config/mcp-clickhousex/config.json` on Unix-like systems or `%USERPROFILE%\.config\mcp-clickhousex\config.json` on Windows. Profile-specific environment variables use the `MCP_CLICKHOUSE_PROFILES_<NAME>_` prefix. URL-reserved characters in credentials must be percent-encoded in the DSN.

## Tools and capabilities

- List configured profiles and their descriptions.
- Inspect ClickHouse version and enforced execution limits.
- List visible databases, tables, views, and columns.
- Run parameterized read-only SELECT queries.
- Execute SHOW introspection statements.
- Analyze query plans, pipelines, or syntax.
- Store larger query results as expiring CSV snapshots.

## Limitations and notes

Write operations are not supported. DML, DDL, SET, SYSTEM, and similar statements are rejected, and `run_show` rejects `INTO OUTFILE`. Interactive query results have a hard ceiling of 1,000 rows, while snapshot results have a hard ceiling of 50,000 rows. Snapshot entries expire after seven days. Query and snapshot limits can be configured but cannot exceed their documented hard ceilings. Results and metadata are limited to what the selected ClickHouse connection can access.

_Full upstream README: https://allmcps.com/mcp/clickhouse/readme_