# ClickHouse/mcp-clickhouse [Health: Active]

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

## Description
ClickHouse database integration with schema inspection and query capabilities

## Tools
Capabilities this server exposes over MCP:

- **list_databases** — List available ClickHouse databases
- **list_tables** — List available ClickHouse tables in a database, including schema, comment,
row count, and column count.

Integers outside [-9007199254740991, 9007199254740991] in table metadata are
returned as decimal strings.
Pagination tokens are single-use and retained for up to one hour.
- **run_query** — Execute SQL queries in ClickHouse. Queries run in read-only mode by default. Bind optional params by name with {name:Type} placeholders, such as {name:String} or {vector:Array(Float32)}. Values may be JSON scalars, nulls, or arrays. Pass exact large integers as decimal strings. JSON lists and objects cannot bind to Tuple and Map types. Python percent formatting and $name$ raw binary parameters are not supported. Parameter values stay out of the MCP server's normal SQL log lines, but may appear in errors and backend logs. Set CLICKHOUSE_ALLOW_WRITE_ACCESS=true to allow DDL and DML operations. Set CLICKHOUSE_ALLOW_DROP=true to additionally allow destructive operations (DROP, TRUNCATE, DELETE, UPDATE, REPLACE TABLE/PARTITION, CREATE OR REPLACE, CLEAR COLUMN/INDEX/PROJECTION, DETACH PERMANENTLY). That gate is a best-effort accident guard, not a security boundary. Integers outside [-9007199254740991, 9007199254740991] are returned as decimal strings. Two optional checks also run through this tool. Use DESCRIBE (<query>) when you need a query's output columns and types; it inspects the result schema and surfaces analysis errors such as an unknown column, but a query that describes cleanly can still fail at runtime. Consider EXPLAIN ESTIMATE <query> before a SELECT that could be expensive; it returns the estimated parts, rows and marks read from MergeTree family tables, which is not run time and not result size. Neither runs the query body, though analysis can execute scalar subqueries.

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

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

## Documentation

## What ClickHouse/mcp-clickhouse MCP server does

ClickHouse/mcp-clickhouse MCP server connects MCP clients to ClickHouse and exposes tools for database discovery, table inspection, and SQL execution. It also provides an optional chDB integration for running queries through chDB's embedded ClickHouse engine.

The ClickHouse tools return JSON-encoded strings. Large integers outside JavaScript's safe integer range are represented as decimal strings, while safe-range integers and booleans retain their normal JSON types.

## How it works

The server supports stdio by default and can also run over HTTP or SSE. Stdio communication does not require authentication. HTTP and SSE deployments require authentication unless authentication is explicitly disabled for local development.

ClickHouse queries run with read-only access by default. Write access can be enabled through an environment setting, and destructive operations such as `DROP` and `TRUNCATE` require a separate setting. This makes the default configuration suitable for agents that only need to inspect data or execute read queries.

For HTTP and SSE deployments, `/health` returns `200 OK` when the server can connect to ClickHouse. It returns `503` when the connection fails or a probe does not complete within two seconds. The endpoint is unauthenticated and reserved for health checks.

## Setup and configuration

The package is published on PyPI as `mcp-clickhouse`. The optional chDB capability requires the `chdb` extra. ClickHouse connection and transport configuration must be supplied according to the deployment environment, while HTTP and SSE authentication can use one of these approaches:

- A static bearer token in `CLICKHOUSE_MCP_AUTH_TOKEN`.
- A FastMCP OAuth or OIDC provider configured through `FASTMCP_SERVER_AUTH` and provider-specific variables.
- `CLICKHOUSE_MCP_AUTH_DISABLED=true` for local development.

HTTP and SSE startup fails when none of the authentication options is configured. The health endpoint remains unauthenticated even when MCP requests require a bearer token or OAuth authentication.

## Tools and capabilities

ClickHouse/mcp-clickhouse MCP server provides these capabilities:

- `list_databases` returns the available ClickHouse databases.
- `list_tables` accepts a database name and can filter table names with `LIKE` or `NOT LIKE` patterns.
- `list_tables` supports pagination with single-use tokens retained for up to one hour. Results include table metadata, matching-table totals, and optionally detailed column information.
- `run_query` executes SQL against the ClickHouse cluster.
- `run_chdb_select_query` executes SQL through chDB when the optional dependency is installed. This can query sources such as files, URLs, and databases without an ETL step.

For large schemas, `list_tables` can omit the detailed columns array while retaining the full create-table query, reducing response size.

## Limitations and notes

The server does not provide unrestricted write access by default. Enabling writes changes the permitted operation set, and destructive statements require an additional explicit setting. Agents should therefore be given only the access level appropriate for their task.

Pagination tokens from `list_tables` are single-use and expire after up to one hour. HTTP health checks do not authenticate and only report a minimal status body; connection failure details must be investigated through server logs.

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