ClickHouse

# ClickHouse MCP Server [](https://pypi.org/project/mcp-clickhouse) 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 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-host>", "CLICKHOUSE_PORT": "<clickhouse-port>", "CLICKHOUSE_USER": "<clickhouse-user>", "CLICKHOUSE_PASSWORD": "<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-host>", "CLICKHOUSE_USER": "<clickhouse-user>", "CLICKHOUSE_PASSWORD": "<clickhouse-password>", "CLICKHOUSE_DATABASE": "<optional-database>" } } } } ``` ## YouTube Overview [](https://www.youtube.com/watch?v=y9biAm_Fkqw)