ClickHouse MCP Server

by clickhouseio.github.ClickHouse/mcp-clickhousev0.7.0

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

883Pythonstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active3d ago

Install ClickHouse MCP server

claude mcp add clickhouse -e CLICKHOUSE_HOST='<clickhouse-host>' -e CLICKHOUSE_USER='<clickhouse-user>' -e CLICKHOUSE_PASSWORD='<clickhouse-password>' -- uvx mcp-clickhouse

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

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

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

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

{
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace.

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

Add to ~/.codeium/windsurf/mcp_config.json.

Configuration

Variable	Required	Secret	Description
CLICKHOUSE_HOST	yes	—	Hostname of the ClickHouse server
CLICKHOUSE_USER	yes	—	Username for ClickHouse authentication
CLICKHOUSE_PASSWORD	—	yes	Password for ClickHouse authentication. Required unless a client certificate uses the default or mutual TLS mode
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_CA_CERT	—	—	Path to a PEM CA bundle for ClickHouse server certificate verification
CLICKHOUSE_CLIENT_CERT	—	—	Path to a PEM client certificate for the ClickHouse HTTPS connection
CLICKHOUSE_CLIENT_CERT_KEY	—	—	Path to the PEM private key for CLICKHOUSE_CLIENT_CERT
CLICKHOUSE_TLS_MODE	—	—	Client certificate mode: mutual, proxy, or strict
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, DELETE, UPDATE, REPLACE, CLEAR, and DETACH PERMANENTLY) when write access is also enabled
CLICKHOUSE_MCP_QUERY_TIMEOUT	—	—	Query tool timeout in seconds
CLICKHOUSE_MCP_MAX_WORKERS	—	—	Maximum query worker thread pool size

Freshness

Active — last maintenance signal 3d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-10-06 · 3d ago · GitHub
Latest release
2026-09-21 · 18d ago · GitHub · v0.7.0
Package published
no data · npm/PyPI
Registry entry updated
2026-09-21 · 18d ago · official registry · v0.7.0

FAQ

›How do I install the ClickHouse MCP server in Claude Code?

Run: claude mcp add clickhouse -e CLICKHOUSE_HOST='<clickhouse-host>' -e CLICKHOUSE_USER='<clickhouse-user>' -e CLICKHOUSE_PASSWORD='<clickhouse-password>' -- uvx mcp-clickhouse. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does ClickHouse require an API key?

Yes. It expects CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, of which 1 is a secret.

›Can I use ClickHouse as a remote (hosted) MCP server?

No hosted endpoint is published; it runs locally over stdio.

›Is ClickHouse in the official MCP registry?

Yes, as io.github.ClickHouse/mcp-clickhouse.