ClickHouse MCP Server

About

ClickHouse MCP Server is ClickHouse's official MCP server (ClickHouse/mcp-clickhouse) that connects Claude, Cursor, and other MCP clients to a ClickHouse cluster for fast analytical querying over natural language. Its primary tool, run_query, executes arbitrary SQL against your cluster in read-only mode by default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false) so an AI assistant can explore tables, aggregate billions of rows, and answer analytics questions without risk of mutating data — writes can be enabled explicitly when needed. Companion tools list databases and tables and return schema metadata (including the full create_table_query, with an option to omit per-column detail for lighter responses). A second tool set embeds chDB, ClickHouse's in-process engine, via run_chdb_select_query, letting the assistant query files, URLs, and external databases directly without an ETL step (enabled with the optional mcp-clickhouse[chdb] extra). Destructive statements are gated a second time: even with writes enabled, DROP and TRUNCATE require CLICKHOUSE_ALLOW_DROP=true as well. The server supports both stdio and HTTP/SSE transports; on HTTP/SSE authentication is required rather than optional — startup fails unless a static bearer token (CLICKHOUSE_MCP_AUTH_TOKEN), a FastMCP OAuth/OIDC provider (Azure Entra, Google, GitHub, WorkOS via FASTMCP_SERVER_AUTH), or an explicit local-development opt-out (CLICKHOUSE_MCP_AUTH_DISABLED) is configured. Connection is configured through CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD, with ClickHouse Cloud, self-hosted, and the public SQL playground all supported.

Installation

uvx mcp-clickhouse

Connecting mcp-clickhouse

1. 1.Try it against the public playground first

   No account, no cluster, no credentials — the demo user on ClickHouse's SQL Playground is read-only and populated with real datasets. This is the config to paste into Claude Desktop if what you want to know is whether the tools are worth wiring to your own data.

   json

   {
     "mcpServers": {
       "mcp-clickhouse": {
         "command": "uv",
         "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
         "env": {
           "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
           "CLICKHOUSE_PORT": "8443",
           "CLICKHOUSE_USER": "demo",
           "CLICKHOUSE_PASSWORD": "",
           "CLICKHOUSE_SECURE": "true",
           "CLICKHOUSE_VERIFY": "true"
         }
       }
     }
   }

2. 2.Point it at your own cluster

   Only three variables are required: `CLICKHOUSE_HOST`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`. Port defaults follow `CLICKHOUSE_SECURE` — 8443 when true, 8123 when false — so on ClickHouse Cloud you can usually leave the port unset entirely. The README is blunt about the user: treat it as any external client, grant the minimum privileges, never the default or an admin account.

   env

   CLICKHOUSE_HOST=your-instance.clickhouse.cloud
   CLICKHOUSE_USER=mcp_readonly
   CLICKHOUSE_PASSWORD=...
   # CLICKHOUSE_SECURE=true is the default and implies port 8443
   # CLICKHOUSE_DATABASE=analytics   # optional, avoids qualifying every table

3. 3.Use the HTTP interface port, not the native one

   This server talks to ClickHouse over the HTTP interface via clickhouse-connect. 8123 plain and 8443 TLS work; 9000 and 9440 are the native TCP protocol that `clickhouse-client` uses and will not work here. If you see `Port 9000 is for clickhouse-client program`, that is the whole diagnosis.

4. 4.Replace `uv` with its absolute path

   Claude Desktop does not inherit your shell PATH, so a bare `uv` resolves inconsistently or not at all. Run `which uv` and paste the result as `command`. The same applies to `python3` or `mcp-clickhouse` if you install from PyPI instead of running it with uv.

   shell

   which uv
   # → /Users/you/.local/bin/uv

5. 5.Turn on writes only if you mean it, and drops separately

   Left alone, queries run with the `readonly=1` setting and mutations are impossible. `CLICKHOUSE_ALLOW_WRITE_ACCESS=true` unlocks DDL and DML; `DROP TABLE`, `DROP DATABASE`, `DROP VIEW`, `DROP DICTIONARY` and `TRUNCATE TABLE` stay blocked until `CLICKHOUSE_ALLOW_DROP=true` is also set. Read-only enforcement also survives being enabled here if the ClickHouse instance itself disallows writes.

   json

   "env": {
     "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
     "CLICKHOUSE_ALLOW_DROP": "true"
   }

6. 6.HTTP transport: authentication is required, not optional

   stdio needs no auth because it never opens a socket. Under `http` or `sse` the process refuses to start unless exactly one of three things is configured: a static bearer token, a FastMCP auth provider, or an explicit development-only opt-out. Generate the token with `uuidgen` or `openssl rand -hex 32` and send it as `Authorization: Bearer <token>`.

   env

   CLICKHOUSE_MCP_SERVER_TRANSPORT=http
   CLICKHOUSE_MCP_BIND_HOST=0.0.0.0
   CLICKHOUSE_MCP_BIND_PORT=4200
   CLICKHOUSE_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
   # MCP endpoint:  http://localhost:4200/mcp
   # Health check:  http://localhost:4200/health

7. 7.For an identity provider, hand auth to FastMCP

   `FASTMCP_SERVER_AUTH` takes the full class path of a FastMCP auth provider — Azure Entra, Google, GitHub, WorkOS — and the provider reads its own `FASTMCP_SERVER_AUTH_*` variables. Leave `CLICKHOUSE_MCP_AUTH_TOKEN` unset in this mode; the two are alternatives, not layers.

   shell

   export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
   export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
   export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
   export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"

8. 8.chDB, if you want queries without a cluster

   chDB is ClickHouse as an in-process engine, and it ships as an optional extra rather than being installed by default. Enabling it alone — `CLICKHOUSE_ENABLED=false` — gives you a server that queries files, URLs and external databases with no ClickHouse deployment behind it at all. `CHDB_DATA_PATH` defaults to `:memory:`; give it a path to persist.

   json

   {
     "command": "uv",
     "args": ["run", "--with", "mcp-clickhouse[chdb]", "--python", "3.10", "mcp-clickhouse"],
     "env": {
       "CHDB_ENABLED": "true",
       "CLICKHOUSE_ENABLED": "false",
       "CHDB_DATA_PATH": "/path/to/chdb/data"
     }
   }

Tools

Four, and the split matters: three go to your ClickHouse cluster, one goes to the embedded chDB engine and never touches it.

What people use it for

Which one should you use?

Categories

Works With

Frequently Asked Questions

Related Guides