# ClickHouse MCP Server > Lets your agent explore your ClickHouse databases, inspect table schemas and run SQL queries, read-only unless you allow writes. ClickHouse's own MCP server. It runs on your machine and lets your agent discover databases and tables, inspect schemas and run SQL against your ClickHouse service, whether that's ClickHouse Cloud or a server you run yourself. Queries are read-only unless you turn writes on. What you can do with it - List the databases on your cluster, and page through the tables in one, with their columns and CREATE TABLE statements - Run SQL queries, with named parameters for the values - Check a query before running it: DESCRIBE shows the columns it returns, and EXPLAIN ESTIMATE shows how many rows it would read - Query files, URLs and other sources in place with chDB, ClickHouse's embedded engine, when you turn it on How it connects It's a Python package, mcp-clickhouse, that runs with uv (for example uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse). It talks to ClickHouse's HTTP interface with the details you give it: CLICKHOUSE_HOST and CLICKHOUSE_USER, plus CLICKHOUSE_PASSWORD, which you need unless you sign in with a client certificate. For ClickHouse Cloud it uses HTTPS on port 8443. For a self-managed server on plain HTTP, also set CLICKHOUSE_SECURE=false, and CLICKHOUSE_PORT=8123 if needed. To try it without your own data, point it at the public ClickHouse SQL Playground: host sql-clickhouse.clickhouse.com, user demo and an empty password. Read-only unless you say so - Queries run read-only by default. - CLICKHOUSE_ALLOW_WRITE_ACCESS=true allows inserts, CREATE and ALTER ADD COLUMN. - Destructive statements such as DROP, TRUNCATE, DELETE and UPDATE also need CLICKHOUSE_ALLOW_DROP=true. - ClickHouse recommends a dedicated database user with only the permissions your agent needs, never a default or admin user: that user's grants are the real limit. Good to know - You need uv installed. If your agent can't find it, use its full path. - ClickHouse documents setup for Claude Code, Claude Desktop, Codex, ChatGPT's desktop app, Cursor and Windsurf. For ChatGPT on the web, ClickHouse Cloud has a separate remote MCP server. - Queries time out after 30 seconds by default; CLICKHOUSE_MCP_QUERY_TIMEOUT changes that. - Type: Plugin - Made by: clickhouse - Category: Databases - Formats: Local MCP - Version: 0.7.0 - Website: https://clickhouse.com/docs/guides/use-cases/ai-ml/MCP/claude-desktop - Source: https://github.com/clickhouse/mcp-clickhouse - Page: https://pluginboard.ai/plugins/clickhouse-mcp ## Works with - Claude - GitHub Copilot - Cursor - Claude Code - Codex - Antigravity - Gemini CLI - OpenClaw - OpenCode - Hermes Agent ## Install You'll need: - `CLICKHOUSE_HOST` (required): Hostname of the ClickHouse server - `CLICKHOUSE_USER` (required): Username for ClickHouse authentication - `CLICKHOUSE_PASSWORD` (optional): Password for ClickHouse authentication. Required unless a client certificate uses the default or mutual TLS mode - `CLICKHOUSE_PORT` (optional): ClickHouse HTTP(S) port. Defaults to 8443 when CLICKHOUSE_SECURE=true, 8123 otherwise - `CLICKHOUSE_SECURE` (optional): Use HTTPS to connect to ClickHouse - `CLICKHOUSE_VERIFY` (optional): Verify SSL certificates - `CLICKHOUSE_CA_CERT` (optional): Path to a PEM CA bundle for ClickHouse server certificate verification - `CLICKHOUSE_CLIENT_CERT` (optional): Path to a PEM client certificate for the ClickHouse HTTPS connection - `CLICKHOUSE_CLIENT_CERT_KEY` (optional): Path to the PEM private key for CLICKHOUSE_CLIENT_CERT - `CLICKHOUSE_TLS_MODE` (optional): Client certificate mode: mutual, proxy, or strict - `CLICKHOUSE_DATABASE` (optional): Default database to use - `CLICKHOUSE_ROLE` (optional): ClickHouse role to activate for the session - `CLICKHOUSE_ALLOW_WRITE_ACCESS` (optional): Allow write operations (DDL and DML). Queries run read-only by default - `CLICKHOUSE_ALLOW_DROP` (optional): Allow destructive operations (DROP, TRUNCATE, DELETE, UPDATE, REPLACE, CLEAR, and DETACH PERMANENTLY) when write access is also enabled - `CLICKHOUSE_MCP_QUERY_TIMEOUT` (optional): Query tool timeout in seconds - `CLICKHOUSE_MCP_MAX_WORKERS` (optional): Maximum query worker thread pool size Replace each `` placeholder with your own value. ### Claude Add to claude_desktop_config.json: ```json { "mcpServers": { "clickhouse-mcp-server": { "command": "uvx", "args": [ "mcp-clickhouse==0.7.0" ], "env": { "CLICKHOUSE_HOST": "", "CLICKHOUSE_USER": "" } } } } ``` ### GitHub Copilot Add to VS Code: vscode:mcp/install?%7B%22name%22%3A%22clickhouse-mcp-server%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-clickhouse%3D%3D0.7.0%22%5D%2C%22env%22%3A%7B%22CLICKHOUSE_HOST%22%3A%22%3CCLICKHOUSE_HOST%3E%22%2C%22CLICKHOUSE_USER%22%3A%22%3CCLICKHOUSE_USER%3E%22%7D%7D Run in your terminal: ```shell code --add-mcp '{"name":"clickhouse-mcp-server","command":"uvx","args":["mcp-clickhouse==0.7.0"],"env":{"CLICKHOUSE_HOST":"","CLICKHOUSE_USER":""}}' ``` Copilot CLI: ```shell copilot mcp add clickhouse-mcp-server --env CLICKHOUSE_HOST= --env CLICKHOUSE_USER= -- uvx mcp-clickhouse==0.7.0 ``` ### Cursor Add to Cursor: cursor://anysphere.cursor-deeplink/mcp/install?name=clickhouse-mcp-server&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtY3AtY2xpY2tob3VzZT09MC43LjAiXSwiZW52Ijp7IkNMSUNLSE9VU0VfSE9TVCI6IjxDTElDS0hPVVNFX0hPU1Q%2BIiwiQ0xJQ0tIT1VTRV9VU0VSIjoiPENMSUNLSE9VU0VfVVNFUj4ifX0%3D Add to .cursor/mcp.json: ```json { "mcpServers": { "clickhouse-mcp-server": { "command": "uvx", "args": [ "mcp-clickhouse==0.7.0" ], "env": { "CLICKHOUSE_HOST": "", "CLICKHOUSE_USER": "" } } } } ``` ### Claude Code Run in your terminal: ```shell claude mcp add -e CLICKHOUSE_HOST= -e CLICKHOUSE_USER= clickhouse-mcp-server -- uvx mcp-clickhouse==0.7.0 ``` ### Codex Run in your terminal: ```shell codex mcp add --env CLICKHOUSE_HOST= --env CLICKHOUSE_USER= clickhouse-mcp-server -- uvx mcp-clickhouse==0.7.0 ``` ### Antigravity Add to ~/.gemini/config/mcp_config.json: ```json { "mcpServers": { "clickhouse-mcp-server": { "command": "uvx", "args": [ "mcp-clickhouse==0.7.0" ], "env": { "CLICKHOUSE_HOST": "", "CLICKHOUSE_USER": "" } } } } ``` ### Gemini CLI Run in your terminal: ```shell gemini mcp add -e CLICKHOUSE_HOST= -e CLICKHOUSE_USER= clickhouse-mcp-server uvx mcp-clickhouse==0.7.0 ``` ### OpenClaw In a terminal: Run openclaw mcp add clickhouse-mcp-server --command uvx, with --arg before each argument (mcp-clickhouse==0.7.0) and --env NAME=value for each variable it needs. ### OpenCode Run in your terminal: ```shell opencode mcp add clickhouse-mcp-server --env CLICKHOUSE_HOST= --env CLICKHOUSE_USER= -- uvx mcp-clickhouse==0.7.0 ``` ### Hermes Agent Add to ~/.hermes/config.yaml: ```json { "mcp_servers": { "clickhouse-mcp-server": { "command": "uvx", "args": [ "mcp-clickhouse==0.7.0" ], "env": { "CLICKHOUSE_HOST": "", "CLICKHOUSE_USER": "" } } } } ``` --- From Pluginboard (https://pluginboard.ai).