mcp-clickhouse
Official
by ClickHouse
ClickHouse MCP Server
An MCP server for ClickHouse.
<a href="https://glama.ai/mcp/servers/yvjy4csvo1"><img width="380" height="200" src="https://glama.ai/mcp/servers/yvjy4csvo1/badge" alt="mcp-clickhouse MCP server" /></a>
Features
Tools
run_select_query
- Execute SQL queries on your ClickHouse cluster.
- Input:
sql
(string): The SQL query to execute. - All ClickHouse queries are run with
readonly = 1
to ensure they are safe.
list_databases
- List all databases on your ClickHouse cluster.
list_tables
- List all tables in a database.
- Input:
database
(string): The name of the database.
Configuration
- Open the Claude Desktop configuration file located at:
- On macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows:
%APPDATA%/Claude/claude_desktop_config.json
- On macOS:
- Add the following:
Copy
Update the environment variables to point to your own ClickHouse service.
Or, if you'd like to try it out with the ClickHouse SQL Playground, you can use the following config:
Copy
- Locate the command entry for
uv
and replace it with the absolute path to theuv
executable. This ensures that the correct version ofuv
is used when starting the server. On a mac, you can find this path usingwhich uv
. - Restart Claude Desktop to apply the changes.
Development
- In
test-services
directory rundocker compose up -d
to start the ClickHouse cluster. - Add the following variables to a
.env
file in the root of the repository.
Copy
- Run
uv sync
to install the dependencies. To installuv
follow the instructions here. Then dosource .venv/bin/activate
. - For easy testing, you can run
fastmcp dev mcp_clickhouse/mcp_server.py
to start the MCP server.
Environment Variables
The following environment variables are used to configure the ClickHouse connection:
Required Variables
CLICKHOUSE_HOST
: The hostname of your ClickHouse serverCLICKHOUSE_USER
: The username for authenticationCLICKHOUSE_PASSWORD
: The password for authentication
Optional Variables
CLICKHOUSE_PORT
: The port number of your ClickHouse server- Default:
8443
if HTTPS is enabled,8123
if disabled - Usually doesn't need to be set unless using a non-standard port
- Default:
CLICKHOUSE_SECURE
: Enable/disable HTTPS connection- Default:
"true"
- Set to
"false"
for non-secure connections
- Default:
CLICKHOUSE_VERIFY
: Enable/disable SSL certificate verification- Default:
"true"
- Set to
"false"
to disable certificate verification (not recommended for production)
- Default:
CLICKHOUSE_CONNECT_TIMEOUT
: Connection timeout in seconds- Default:
"30"
- Increase this value if you experience connection timeouts
- Default:
CLICKHOUSE_SEND_RECEIVE_TIMEOUT
: Send/receive timeout in seconds- Default:
"300"
- Increase this value for long-running queries
- Default:
CLICKHOUSE_DATABASE
: Default database to use- Default: None (uses server default)
- Set this to automatically connect to a specific database
Example Configurations
For local development with Docker:
Copy
For ClickHouse Cloud:
Copy
For ClickHouse SQL Playground:
Copy
You can set these variables in your environment, in a .env
file, or in the Claude Desktop configuration:
Copy
You must be authenticated.
ClickHouse database integration with schema inspection and query capabilities