How to add ClickHouse MCP Server to Cursor

Official ClickHouse server: read-only SQL queries plus database/table exploration and chDB support. Paste the config into ~/.cursor/mcp.json and restart Cursor.

Last updated June 15, 2026 · 1.0k★ · stdio · apikey · official

Cursor config for ClickHouse MCP Server

uvx mcp-clickhouse

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>"
      }
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

1Open Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
2Paste the ClickHouse MCP Server config below into the "mcpServers" object.
3Fill in placeholder secrets, then save.
4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
5Ask Cursor to use one of ClickHouse MCP Server's tools to confirm it's connected.

Before you start

Python 3.10+ and the uv package manager (or pip)
A ClickHouse instance and credentials: CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD (ClickHouse Cloud, a local server, or the ClickHouse SQL Playground all work)
Optionally chDB if you want to query files directly — install the extra with pip install 'mcp-clickhouse[chdb]' and set CHDB_ENABLED=true
For remote/HTTP deployments: optionally a bearer token (CLICKHOUSE_MCP_AUTH_TOKEN) or an OAuth/OIDC provider

What ClickHouse MCP Server can do in Cursor

run_query

Execute a SQL query against ClickHouse (read-only by default)

list_databases

List all databases in the ClickHouse instance

list_tables

List tables in a database, with pagination and filtering, including schema details

run_chdb_select_query

Run a SELECT query using the embedded chDB engine (e.g. over files/S3) without a ClickHouse server

Security

Queries run read-only by default, which is the recommended posture; only relax this for trusted workloads. Credentials are passed via env vars, so keep them out of shell history and use a least-privilege ClickHouse user.

ClickHouse MCP Server + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the ClickHouse MCP Server config there under the "mcpServers" key and restart the client.

Is ClickHouse MCP Server safe to use with Cursor?

Is it read-only or can it modify data?

Read-only by default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false). You can enable writes explicitly, and destructive operations like DROP require an additional flag (CLICKHOUSE_ALLOW_DROP).

What is the chDB tool for?

run_chdb_select_query uses chDB, ClickHouse's embedded engine, to run SELECT queries directly over files and external sources (Parquet, CSV, S3, URLs) without needing a running ClickHouse server. Enable it with the chdb extra and CHDB_ENABLED=true.

Can I try it without my own ClickHouse server?

Yes. Point the CLICKHOUSE_* variables at the public ClickHouse SQL Playground (host sql-clickhouse.clickhouse.com, user demo, no password) to explore sample datasets, or use chDB over files.

View repo Full ClickHouse MCP Server page