MCP Directory

How to add ClickHouse MCP Server to Windsurf

Official ClickHouse server: read-only SQL queries plus database/table exploration and chDB support. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf 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

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the ClickHouse MCP Server config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5ClickHouse MCP Server's tools become available to Cascade.

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 Windsurf

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 + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the ClickHouse MCP Server config there under the "mcpServers" key and restart the client.

Is ClickHouse MCP Server safe to use with Windsurf?

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.

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