https://github.com/ClickHouse/mcp-clickhouse
https://github.com/ClickHouse/mcp-clickhouse
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/ClickHouse/mcp-clickhouse
- Owner: ClickHouse
- License: apache-2.0
- Created: 2024-12-25T14:15:46.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-02-27T23:29:17.000Z (about 2 months ago)
- Last Synced: 2025-02-28T08:12:41.139Z (about 2 months ago)
- Language: Python
- Size: 52.7 KB
- Stars: 60
- Watchers: 5
- Forks: 14
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - ClickHouse - Interact with your [ClickHouse](https://clickhouse.com/) analytical database (🏢 Enterprise-Supported Implementations / Databases & Storage)
- awesome-mcp-servers - ClickHouse - Interact with your [ClickHouse](https://clickhouse.com/) analytical database (🏢 Enterprise-Supported Implementations / Databases & Storage)
- awesome-mcp-list - ClickHouse/mcp-clickhouse - clickhouse?style=social)](https://github.com/ClickHouse/mcp-clickhouse): Offers schema inspection and querying capabilities for ClickHouse databases. (Uncategorized / Uncategorized)
- awesome-mcp-servers - ClickHouse/mcp-clickhouse - ClickHouse database integration with schema inspection and query capabilities (Legend / 🗄️ <a name="databases"></a>Databases)
- awesome-mcp-servers - ClickHouse/mcp-clickhouse - ClickHouse database integration with schema inspection and query capabilities (Legend / 🗄️ <a name="databases"></a>Databases)
- Awesome-MCP-Servers-directory - ClickHouse - Query your ClickHouse database server (Databases)
- awesome-mcp-servers - ClickHouse MCP - Executes ClickHouse SQL queries and manages databases and tables via a server interface (Table of Contents / Databases)
- awesome-mcp-servers - ClickHouse MCP - Executes ClickHouse SQL queries and manages databases and tables via a server interface (Table of Contents / Databases)
- awesome-clickhouse - ClickHouse/mcp-clickhouse - ClickHouse MCP Server is a multi-channel processing server for executing SQL queries and managing ClickHouse database clusters. (Integrations / Deployment and Management Tools)
- awesome-mcp-servers - ClickHouse - Query your [ClickHouse](https://clickhouse.com/) database server. (Official Servers)
- awesome-mcp-zh - ClickHouse/mcp-clickhouse
- awesome-mcp-zh - ClickHouse/mcp-clickhouse
README
# 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": ""
}
}
}
}
```