Log inSubmit server
MCP Clickhouse logo

MCP Clickhouse

by ClickHouse

Inspect ClickHouse schemas and run SQL through MCP, with optional write controls and embedded chDB queries.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install MCP Clickhouse

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "clickhouse-mcp-clickhouse": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Automated check passed— started and listed 3 tools correctly (1mo ago).

Overview

ClickHouse/mcp-clickhouse MCP server exposes ClickHouse database inspection and SQL execution through MCP. It can list databases, inspect tables with schema metadata and pagination, and run queries in read-only mode by default. An optional chDB tool runs queries through an embedded ClickHouse engine against files, URLs, and databases. Reach for it when an agent needs structured access to a ClickHouse cluster or local chDB query execution.

Use cases

  • List ClickHouse databases and tables for schema discovery
  • Run read-only SQL queries against a ClickHouse cluster
  • Filter and paginate large ClickHouse table inventories
  • Query files or URLs through the optional chDB engine

Key features

  • List ClickHouse databases
  • Inspect tables and column metadata
  • Execute read-only ClickHouse SQL
  • Control write and destructive access
  • Run optional chDB queries
  • Expose an HTTP/SSE health endpoint

Tools3

What MCP Clickhouse lets your agent do. Expand a tool for its parameters.

Verified live~787 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

20/20 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · mcp-clickhouse (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars893Stargazers on the source repository.
Last commit1d agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed3Callable tools this server registers over MCP.
Directory activity6 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Clickhouse works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about MCP Clickhouse

The project is published on PyPI as `mcp-clickhouse`.

Yes. The documentation includes a Claude Desktop configuration example for connecting over HTTP with a bearer token.

Queries are read-only by default. Set `CLICKHOUSE_ALLOW_WRITE_ACCESS=true` to enable DDL and DML, and set `CLICKHOUSE_ALLOW_DROP=true` to additionally allow `DROP` and `TRUNCATE` operations.

Call `list_tables` with a database name. You can add name filters, pagination settings, and the option to omit detailed column metadata.

Install the optional `chdb` extra using the package's documented extra, then use `run_chdb_select_query` to execute queries through chDB.

Related MCP servers

All in Databases All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMCP Clickhouse AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/clickhouse-mcp-clickhouse?style=directory)](https://allmcps.com/mcp/clickhouse-mcp-clickhouse)
HTML Embed
<a href="https://allmcps.com/mcp/clickhouse-mcp-clickhouse"><img src="https://allmcps.com/api/badge/clickhouse-mcp-clickhouse?style=directory" alt="MCP Clickhouse on AllMCPs" /></a>