ClickHouse — Claude Code MCP server: queries and setup
This MCP server connects Claude Code to ClickHouse clusters and chDB for SQL queries, database discovery, and table browsing.
claude mcp add --env CLICKHOUSE_HOST=<CLICKHOUSE_HOST> --env CLICKHOUSE_USER=<CLICKHOUSE_USER> --env CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> --env CLICKHOUSE_PORT=<CLICKHOUSE_PORT> --env CLICKHOUSE_SECURE=<CLICKHOUSE_SECURE> --transport stdio clickhouse -- uvx mcp-clickhouseWhat ClickHouse does
ClickHouse exposes tools for working with data: run_query executes SQL, list_databases returns databases, and list_tables browses tables with pagination. Table lookup can filter names and include column details. Queries use read-only mode by default.
Values can be sent separately through params and ClickHouse placeholders such as {name:Type}. The run_query tool also accepts DESCRIBE for inspecting result columns and EXPLAIN ESTIMATE for estimating reads. The connection needs CLICKHOUSE_HOST, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD; port and secure transport use separate environment variables.
What it helps with
- run SQL queries against a ClickHouse cluster
- browse ClickHouse databases and tables
- bind values to parameterized SQL queries
- inspect result columns before execution
- estimate reads for a SELECT query
Example prompts for the agent
- Run a ClickHouse query that groups sales from
eventsby day. - List the ClickHouse databases and then show tables matching
orders. - Use
DESCRIBEto inspect this query’s result columns, then runEXPLAIN ESTIMATEfor its read estimate.
How to install ClickHouse
Platform CLI
claude mcp add --env CLICKHOUSE_HOST=<CLICKHOUSE_HOST> --env CLICKHOUSE_USER=<CLICKHOUSE_USER> --env CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> --env CLICKHOUSE_PORT=<CLICKHOUSE_PORT> --env CLICKHOUSE_SECURE=<CLICKHOUSE_SECURE> --transport stdio clickhouse -- uvx mcp-clickhouseReplace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>
Platform CLI
codex mcp add clickhouse --env CLICKHOUSE_HOST=<CLICKHOUSE_HOST> --env CLICKHOUSE_USER=<CLICKHOUSE_USER> --env CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> --env CLICKHOUSE_PORT=<CLICKHOUSE_PORT> --env CLICKHOUSE_SECURE=<CLICKHOUSE_SECURE> -- uvx mcp-clickhouseReplace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>
Config file
{
"mcpServers": {
"clickhouse": {
"command": "uvx",
"args": [
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
"CLICKHOUSE_USER": "<CLICKHOUSE_USER>",
"CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>",
"CLICKHOUSE_PORT": "<CLICKHOUSE_PORT>",
"CLICKHOUSE_SECURE": "<CLICKHOUSE_SECURE>"
}
}
}
}Replace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>
Config file
{
"servers": {
"clickhouse": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
"CLICKHOUSE_USER": "<CLICKHOUSE_USER>",
"CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>",
"CLICKHOUSE_PORT": "<CLICKHOUSE_PORT>",
"CLICKHOUSE_SECURE": "<CLICKHOUSE_SECURE>"
}
}
}
}Replace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>
Platform CLI
gemini mcp add -e CLICKHOUSE_HOST=<CLICKHOUSE_HOST> -e CLICKHOUSE_USER=<CLICKHOUSE_USER> -e CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> -e CLICKHOUSE_PORT=<CLICKHOUSE_PORT> -e CLICKHOUSE_SECURE=<CLICKHOUSE_SECURE> clickhouse uvx mcp-clickhouseReplace <…> with your own values. 11 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-clickhouse <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ClickHouse
How do I install ClickHouse in Claude Code?
Run `claude mcp add mcp-clickhouse -e CLICKHOUSE_HOST=<CLICKHOUSE_HOST> -e CLICKHOUSE_USER=<CLICKHOUSE_USER> -e CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> -- uvx mcp-clickhouse`.
What does the ClickHouse MCP server do?
It lets an agent run SQL against ClickHouse, list databases, and browse tables. The run_query tool also supports DESCRIBE and EXPLAIN ESTIMATE.
How are SQL parameters passed?
Send values in the params object and use ClickHouse placeholders such as {name:Type} in the query. %s, %(name)s, and $name$ formats are not supported for this parameter binding.
