# ClickHouse MCP Server (slim)

> ClickHouse's open-source MCP server for ClickHouse databases. The owner runs it locally or self-hosted, and it gives agents SQL queries, database and table listing, and an optional embedded chDB engine. Queries are read-only by default.

- Full: https://www.anchorterminal.com/tools/clickhouse-mcp-server.md (~7,800 tokens) · this version ~1,730 tokens · JSON https://www.anchorterminal.com/tools/clickhouse-mcp-server.json · canonical https://www.anchorterminal.com/tools/clickhouse-mcp-server
- Index: https://www.anchorterminal.com/llms.txt · API: https://www.anchorterminal.com/api/v1/index.json · Updated: 2026-10-09

**B · 64.6/100 · rank #312 of 842 · #5 in Databases & files · not agent-ready · confidence medium**


Assessment: Queries run with `readonly=1` unless the operator sets a write flag, and a second flag gates destructive statements. `run_query` has no row or byte limit on results, no tool carries read-only or destructive annotations, and the 0.3.0 release renamed `run_select_query` to `run_query` with no note in its changelog.

## Facts

- Kind: MCP server · vendor: ClickHouse · category: Databases & files · legal entity: ClickHouse, Inc. · provenance 87/100
- Local only (stdio, Streamable HTTP, SSE (legacy)): pypi `mcp-clickhouse`, oci `ghcr.io/clickhouse/mcp-clickhouse`
- Auth: OAuth or key · pricing: Free · x402: no · licence: Apache-2.0
- Probe metrics: not measured yet (probes haven't run)
- What is graded: The open-source server in ClickHouse/mcp-clickhouse, version 0.7.0, which the owner runs. ClickHouse Cloud's hosted Remote MCP server at `https://mcp.clickhouse.cloud/mcp` is a separate product with 13 read-only tools and is not graded here
- Install: `python3 -m pip install mcp-clickhouse` or `uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse`. Python 3.10 to 3.14. Docker images at `ghcr.io/clickhouse/mcp-clickhouse` since 0.4.0. chDB needs the extra, `pip install 'mcp-clickhouse[chdb]'`
- Transports: stdio (default), streamable HTTP (`CLICKHOUSE_MCP_SERVER_TRANSPORT=http`, endpoint `/mcp` on `127.0.0.1:8000`) and SSE, which is deprecated and logs a warning. `/health` is unauthenticated on HTTP and SSE
- Tools: `run_query` (`query`, optional `params`), `list_databases` (no inputs), `list_tables` (`database`, optional `like`, `not_like`, `page_token`, `page_size` default 50, `include_detailed_columns`). `run_chdb_select_query` (`query`) when chDB is enabled. Results are JSON-encoded strings
- Credentials: `CLICKHOUSE_HOST`, `CLICKHOUSE_USER` and `CLICKHOUSE_PASSWORD`, or a client certificate with `CLICKHOUSE_CLIENT_CERT` and `CLICKHOUSE_TLS_MODE` (mutual, proxy or strict). Optional `CLICKHOUSE_ROLE`. The connection uses ClickHouse's HTTP interface on 8443 or 8123, not the native protocol
- Restrictions: `readonly=1` by default. `CLICKHOUSE_ALLOW_WRITE_ACCESS=true` for DDL and inserts, plus `CLICKHOUSE_ALLOW_DROP=true` for destructive statements. With write access on and drop off, the server reads `SHOW GRANTS` once and logs a warning if the user holds destructive privileges
- HTTP protections: Authentication required by default. `CLICKHOUSE_MCP_ALLOWED_HOSTS` and `CLICKHOUSE_MCP_ALLOWED_ORIGINS` validate Host (421 on mismatch) and Origin (403). A wildcard bind refuses to start without an allowed-hosts list. `CLICKHOUSE_MCP_TRUSTED_PROXIES` for `X-Forwarded-Host`
- Limits: `CLICKHOUSE_MCP_QUERY_TIMEOUT` 30 seconds by default, after which the server attempts `KILL QUERY`. `CLICKHOUSE_MCP_MAX_WORKERS` 10. No row or byte limit on `run_query` results
- Usage statistics: No telemetry code was found in the 0.7.0 source. The server sends the client name `mcp_clickhouse` to the ClickHouse it connects to and logs each query's SQL text at INFO level
- Releases: 0.1.0 on 24 December 2024. 0.3.0 on 14 April 2026 (write mode, tool renamed to `run_query`), 0.4.0 on 3 June, 0.4.1 on 17 July, 0.5.0 on 1 September, 0.6.0 on 3 September (FastMCP 4), 0.7.0 tagged 21 September 2026

- Scores: Reliability 74, Performance pending, Schema & documentation 79, Agent ergonomics 65, Security & auth 66, Payments & pricing 60, Task success pending, Maintenance & community 94, Transparency & trust 82 · negative events -8 · total over the 7 assessed categories
- Why: Reliability, Scored as local software, since the owner runs it over stdio or its own HTTP listener. · Schema & documentation, Each tool is built from a typed Python signature, so inputs carry JSON Schema, read from the source since we do not run vendor software. · Agent ergonomics, Three tools by default and four with chDB, one of them with a long description (25). · Security & auth, The server holds one ClickHouse user and password, or an X.509 client certificate since 0.7.0, which ClickHouse grants and roles can scope a… · Payments & pricing, Read with the self-hosted rule. · Maintenance & community, v0.7.0 was tagged and released on GitHub on 21 September 2026, 18 days before the check (30). · Transparency & trust, Apache-2.0 (30).
- Sources: 26, open questions: 9, both in the full twin
- Capabilities: db.sql
- JSON: https://www.anchorterminal.com/api/v1/tools/clickhouse-mcp-server.json
- Verify (for the vendor): the badge `https://www.anchorterminal.com/badges/clickhouse-mcp-server.svg` or a link to https://www.anchorterminal.com/tools/clickhouse-mcp-server from a page on clickhouse.com or one of its subdomains, or the README of github.com/ClickHouse/mcp-clickhouse, then `POST https://www.anchorterminal.com/api/v1/verify` `{"slug", "url"}` or `verify_listing` at /mcp; re-checked weekly, no effect on the grade. Snippets in the full twin.

## Before you call it

1. Put a `LIMIT` on every `run_query` call. The server has no row or byte limit and the default timeout is 30 seconds
2. Call the tool `run_query`. ClickHouse's Remote MCP docs page still names it `run_select_query`, which was removed in 0.3.0
3. Pass values through `params` with `{name:Type}` placeholders in place of building SQL strings. Tuple and Map types can't be bound
4. Set `include_detailed_columns` to false on `list_tables` for wide schemas. Page tokens are single-use and expire after one hour
5. Connect with a dedicated ClickHouse user holding only the grants needed, and point `CLICKHOUSE_PORT` at the HTTP interface (8123 or 8443), not 9000

## Connect

```bash
python3 -m pip install mcp-clickhouse
```
Full config and headless snippets are in the full page. Through letme (picks today, calling later): https://letme.dev/clickhouse-mcp-server

## Similar tools

| Tool | Grade | Score | Shared capabilities | Slim |
| --- | --- | --- | --- | --- |
| Supabase API + MCP | BB | 75.6 | db.sql | https://www.anchorterminal.com/tools/supabase-mcp.min.md |
| Render MCP Server | B | 63.6 | db.sql | https://www.anchorterminal.com/tools/render-mcp-server.min.md |
| Atlan | B | 62.5 | db.sql | https://www.anchorterminal.com/tools/atlan.min.md |
| Alation | C | 60.3 | db.sql | https://www.anchorterminal.com/tools/alation.min.md |
| Postgres MCP Pro | F | 36.7 | db.sql | https://www.anchorterminal.com/tools/postgres-mcp-pro.min.md |


## Panel reviews (0, desk reviews from public material, no calls made)