ClickHouse MCP Server

Name: ClickHouse MCP Server
Author: io.github.ClickHouse

io.github.ClickHouse/mcp-clickhouse

Repository Registry

What is the ClickHouse MCP server?

Official ClickHouse MCP server for querying and exploring ClickHouse clusters and chDB.

How to install ClickHouse

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

CLICKHOUSE_HOST
required
Hostname of the ClickHouse server
CLICKHOUSE_USER
required
Username for ClickHouse authentication
CLICKHOUSE_PASSWORD
required
secret
Password for ClickHouse authentication
CLICKHOUSE_PORT
ClickHouse HTTP(S) port. Defaults to 8443 when CLICKHOUSE_SECURE=true, 8123 otherwise
CLICKHOUSE_SECURE
Use HTTPS to connect to ClickHouse
CLICKHOUSE_VERIFY
Verify SSL certificates
CLICKHOUSE_DATABASE
Default database to use
CLICKHOUSE_ROLE
ClickHouse role to activate for the session
CLICKHOUSE_ALLOW_WRITE_ACCESS
Allow write operations (DDL and DML). Queries run read-only by default
CLICKHOUSE_ALLOW_DROP
Allow destructive operations (DROP, TRUNCATE) when write access is also enabled
CLICKHOUSE_MCP_QUERY_TIMEOUT
Query tool timeout in seconds

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<YOUR_CLICKHOUSE_HOST>",
        "CLICKHOUSE_USER": "<YOUR_CLICKHOUSE_USER>",
        "CLICKHOUSE_PASSWORD": "<YOUR_CLICKHOUSE_PASSWORD>",
        "CLICKHOUSE_PORT": "<YOUR_CLICKHOUSE_PORT>",
        "CLICKHOUSE_SECURE": "<YOUR_CLICKHOUSE_SECURE>",
        "CLICKHOUSE_VERIFY": "<YOUR_CLICKHOUSE_VERIFY>",
        "CLICKHOUSE_DATABASE": "<YOUR_CLICKHOUSE_DATABASE>",
        "CLICKHOUSE_ROLE": "<YOUR_CLICKHOUSE_ROLE>",
        "CLICKHOUSE_ALLOW_WRITE_ACCESS": "<YOUR_CLICKHOUSE_ALLOW_WRITE_ACCESS>",
        "CLICKHOUSE_ALLOW_DROP": "<YOUR_CLICKHOUSE_ALLOW_DROP>",
        "CLICKHOUSE_MCP_QUERY_TIMEOUT": "<YOUR_CLICKHOUSE_MCP_QUERY_TIMEOUT>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<YOUR_CLICKHOUSE_HOST>",
        "CLICKHOUSE_USER": "<YOUR_CLICKHOUSE_USER>",
        "CLICKHOUSE_PASSWORD": "<YOUR_CLICKHOUSE_PASSWORD>",
        "CLICKHOUSE_PORT": "<YOUR_CLICKHOUSE_PORT>",
        "CLICKHOUSE_SECURE": "<YOUR_CLICKHOUSE_SECURE>",
        "CLICKHOUSE_VERIFY": "<YOUR_CLICKHOUSE_VERIFY>",
        "CLICKHOUSE_DATABASE": "<YOUR_CLICKHOUSE_DATABASE>",
        "CLICKHOUSE_ROLE": "<YOUR_CLICKHOUSE_ROLE>",
        "CLICKHOUSE_ALLOW_WRITE_ACCESS": "<YOUR_CLICKHOUSE_ALLOW_WRITE_ACCESS>",
        "CLICKHOUSE_ALLOW_DROP": "<YOUR_CLICKHOUSE_ALLOW_DROP>",
        "CLICKHOUSE_MCP_QUERY_TIMEOUT": "<YOUR_CLICKHOUSE_MCP_QUERY_TIMEOUT>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<YOUR_CLICKHOUSE_HOST>",
        "CLICKHOUSE_USER": "<YOUR_CLICKHOUSE_USER>",
        "CLICKHOUSE_PASSWORD": "<YOUR_CLICKHOUSE_PASSWORD>",
        "CLICKHOUSE_PORT": "<YOUR_CLICKHOUSE_PORT>",
        "CLICKHOUSE_SECURE": "<YOUR_CLICKHOUSE_SECURE>",
        "CLICKHOUSE_VERIFY": "<YOUR_CLICKHOUSE_VERIFY>",
        "CLICKHOUSE_DATABASE": "<YOUR_CLICKHOUSE_DATABASE>",
        "CLICKHOUSE_ROLE": "<YOUR_CLICKHOUSE_ROLE>",
        "CLICKHOUSE_ALLOW_WRITE_ACCESS": "<YOUR_CLICKHOUSE_ALLOW_WRITE_ACCESS>",
        "CLICKHOUSE_ALLOW_DROP": "<YOUR_CLICKHOUSE_ALLOW_DROP>",
        "CLICKHOUSE_MCP_QUERY_TIMEOUT": "<YOUR_CLICKHOUSE_MCP_QUERY_TIMEOUT>"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "mcp-clickhouse": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<YOUR_CLICKHOUSE_HOST>",
        "CLICKHOUSE_USER": "<YOUR_CLICKHOUSE_USER>",
        "CLICKHOUSE_PASSWORD": "<YOUR_CLICKHOUSE_PASSWORD>",
        "CLICKHOUSE_PORT": "<YOUR_CLICKHOUSE_PORT>",
        "CLICKHOUSE_SECURE": "<YOUR_CLICKHOUSE_SECURE>",
        "CLICKHOUSE_VERIFY": "<YOUR_CLICKHOUSE_VERIFY>",
        "CLICKHOUSE_DATABASE": "<YOUR_CLICKHOUSE_DATABASE>",
        "CLICKHOUSE_ROLE": "<YOUR_CLICKHOUSE_ROLE>",
        "CLICKHOUSE_ALLOW_WRITE_ACCESS": "<YOUR_CLICKHOUSE_ALLOW_WRITE_ACCESS>",
        "CLICKHOUSE_ALLOW_DROP": "<YOUR_CLICKHOUSE_ALLOW_DROP>",
        "CLICKHOUSE_MCP_QUERY_TIMEOUT": "<YOUR_CLICKHOUSE_MCP_QUERY_TIMEOUT>"
      }
    }
  }
}

Claude Code

claude mcp add mcp-clickhouse --env CLICKHOUSE_HOST=<YOUR_CLICKHOUSE_HOST> --env CLICKHOUSE_USER=<YOUR_CLICKHOUSE_USER> --env CLICKHOUSE_PASSWORD=<YOUR_CLICKHOUSE_PASSWORD> --env CLICKHOUSE_PORT=<YOUR_CLICKHOUSE_PORT> --env CLICKHOUSE_SECURE=<YOUR_CLICKHOUSE_SECURE> --env CLICKHOUSE_VERIFY=<YOUR_CLICKHOUSE_VERIFY> --env CLICKHOUSE_DATABASE=<YOUR_CLICKHOUSE_DATABASE> --env CLICKHOUSE_ROLE=<YOUR_CLICKHOUSE_ROLE> --env CLICKHOUSE_ALLOW_WRITE_ACCESS=<YOUR_CLICKHOUSE_ALLOW_WRITE_ACCESS> --env CLICKHOUSE_ALLOW_DROP=<YOUR_CLICKHOUSE_ALLOW_DROP> --env CLICKHOUSE_MCP_QUERY_TIMEOUT=<YOUR_CLICKHOUSE_MCP_QUERY_TIMEOUT> -- uvx mcp-clickhouse