Information
# ClickHouse MCP Server
[](https://pypi.org/project/mcp-clickhouse)
An MCP server for ClickHouse.
## 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
1. 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\`
2. Add the following:
\`\`\`json
\{
"mcpServers": \{
"mcp-clickhouse": \{
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.13",
"mcp-clickhouse"
],
"env": \{
"CLICKHOUSE_HOST": "",
"CLICKHOUSE_PORT": "",
"CLICKHOUSE_USER": "",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
\}
\}
\}
\}
\`\`\`
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](https://sql.clickhouse.com/), you can use the following config:
\`\`\`json
\{
"mcpServers": \{
"mcp-clickhouse": \{
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.13",
"mcp-clickhouse"
],
"env": \{
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "demo",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
\}
\}
\}
\}
\`\`\`
3. Locate the command entry for \`uv\` and replace it with the absolute path to the \`uv\` executable. This ensures that the correct version of \`uv\` is used when starting the server. On a mac, you can find this path using \`which uv\`.
4. Restart Claude Desktop to apply the changes.
## Development
1. In \`test-services\` directory run \`docker compose up -d\` to start the ClickHouse cluster.
2. Add the following variables to a \`.env\` file in the root of the repository.
\`\`\`
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
\`\`\`
3. Run \`uv sync\` to install the dependencies. To install \`uv\` follow the instructions [here](https://docs.astral.sh/uv/). Then do \`source .venv/bin/activate\`.
4. For easy testing, you can run \`mcp 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 server
* \`CLICKHOUSE_USER\`: The username for authentication
* \`CLICKHOUSE_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
* \`CLICKHOUSE_SECURE\`: Enable/disable HTTPS connection
- Default: \`"true"\`
- Set to \`"false"\` for non-secure connections
* \`CLICKHOUSE_VERIFY\`: Enable/disable SSL certificate verification
- Default: \`"true"\`
- Set to \`"false"\` to disable certificate verification (not recommended for production)
* \`CLICKHOUSE_CONNECT_TIMEOUT\`: Connection timeout in seconds
- Default: \`"30"\`
- Increase this value if you experience connection timeouts
* \`CLICKHOUSE_SEND_RECEIVE_TIMEOUT\`: Send/receive timeout in seconds
- Default: \`"300"\`
- Increase this value for long-running queries
* \`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:
\`\`\`env
# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false
\`\`\`
For ClickHouse Cloud:
\`\`\`env
# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database
\`\`\`
For ClickHouse SQL Playground:
\`\`\`env
CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)
\`\`\`
You can set these variables in your environment, in a \`.env\` file, or in the Claude Desktop configuration:
\`\`\`json
\{
"mcpServers": \{
"mcp-clickhouse": \{
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.13",
"mcp-clickhouse"
],
"env": \{
"CLICKHOUSE_HOST": "",
"CLICKHOUSE_USER": "",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_DATABASE": ""
\}
\}
\}
\}
\`\`\`
## YouTube Overview
[](https://www.youtube.com/watch?v=y9biAm_Fkqw)