Content
# ClickHouse Readonly MCP
A FastMCP server for executing read-only ClickHouse queries, supporting local Python API integration and running as a standalone service.
## Updates
**20250509**: Added the official clickhouse mcp code and optimized it to avoid multiple call loops.
## Features
- Support executing read-only SQL queries using the MCP tool
- Input validation ensures that only read-only operations such as SELECT, SHOW, DESCRIBE, EXPLAIN, etc. can be executed
- Support for HTTP and native ClickHouse connection methods with automatic failover
- Concise tabular format output results
- Support for parameterized queries
- High-performance query execution and result processing
## Installation
### Install via pip
```bash
pip install clickhouse-readonly-mcp
```
### Install from source
```bash
git clone https://github.com/the-nine-nation/clickhouse-mcp.git
cd clickhouse-readonly-mcp
pip install -e .
```
## Usage
For example, using a cursor, add the following dictionary to config.json:
Where sys.executable is the executable file of the Python virtual environment, usually named python, conda, or uv
clickhouse_mcp_py is the absolute path to main.py
```json
"clickhouse": {
"command": sys.executable,
"args": [clickhouse_mcp_py],
"env": {
"CLICKHOUSE_ENABLED": "true",
"CLICKHOUSE_HOST": "ClickHouse database IP",
"CLICKHOUSE_PORT": "ClickHouse database port",
"CLICKHOUSE_HTTP_PORT":"",
"CLICKHOUSE_DATABASE": "ClickHouse database name",
"CLICKHOUSE_USERNAME": "ClickHouse database username",
"CLICKHOUSE_PASSWORD": "ClickHouse database password",
"CLICKHOUSE_RESOURCE_DESC_FILE": "Path to ClickHouse database resource description file"
}
}
```
Or use our optimized official implementation:
```json
"clickhouse": {
"command": sys.executable,
"args": [clickhouse_mcp_py],
"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"
}
```
Please note:
1. CLICKHOUSE_PORT is the native connection port, CLICKHOUSE_HTTP_PORT is the HTTP protocol port, and this MCP will automatically switch, so not all of them need to be filled in;
2. CLICKHOUSE_RESOURCE_DESC_FILE is a description that can put some information about the database into it, such as what tables are used for, which can improve the model's understanding ability.
3. CLICKHOUSE_ENABLED does not need to be filled in by default.
## License
MIT
