# ClickHouse/mcp-clickhouse [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/ClickHouse/mcp-clickhouse  
**GitHub Stars:** 869  
**Views:** 3  
**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.

Args:
    database: The database to list tables from
    like: Optional LIKE pattern to filter table names
    not_like: Optional NOT LIKE pattern to exclude table names
    page_token: Token for pagination, obtained from a previous call
    page_size: Number of tables to return per page (default: 50)
    include_detailed_columns: Whether to include detailed column metadata (default: True).
        When False, the columns array will be empty but create_table_query still contains
        all column information. This reduces payload size for large schemas.

Returns:
    A JSON-encoded string of an object containing:
    - tables: List of table information (as dictionaries)
    - next_page_token: Token for the next page, or None if no more pages
    - total_tables: Total number of tables matching the filters
- **run_query** — Execute SQL queries in ClickHouse. Queries run in read-only mode by default. Set CLICKHOUSE_ALLOW_WRITE_ACCESS=true to allow DDL and DML operations. Set CLICKHOUSE_ALLOW_DROP=true to additionally allow destructive operations (DROP, TRUNCATE).

## 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.

The available material does not identify a software license or provide a confirmed one-line command for launching the server directly, so installation and licensing details should be verified from the project distribution before automation.

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