Best for
- Teams already using ClickHouse who want AI assistants to access data directly.
- Scenarios requiring fast, read-only data queries and schema exploration.
M
79FMRS · B
Official MCP server with comprehensive features, but careful attention to permission configuration and security is needed.
Official ClickHouse MCP server for querying and exploring ClickHouse clusters and chDB. Provides SQL query, database and table listing tools via MCP.
Tools
run_query
Execute SQL queries on your ClickHouse cluster. Read-only by default.
list_databases
List all databases on your ClickHouse cluster.
list_tables
List tables in a database with pagination and filtering.
run_chdb_select_query
Execute SQL queries using chDB's embedded ClickHouse engine.
Setup
- Install dependencies: uv or Python.
- Add mcpServers entry to Claude Desktop config (see install_config).
- Set environment variables CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD.
- Restart Claude Desktop.
claude_desktop_config.json
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "<clickhouse-host>",
"CLICKHOUSE_PORT": "<clickhouse-port>",
"CLICKHOUSE_USER": "<clickhouse-user>",
"CLICKHOUSE_PASSWORD": "<clickhouse-password>",
"CLICKHOUSE_ROLE": "<clickhouse-role>",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
}
}
}
}
Fit and risk
Not for
- Scenarios requiring write access to the database without explicit opt-in.
- Production environments with stringent security requirements that avoid default permission settings.
Required permissions
- Requires read-only access to ClickHouse database (default).
- Optional: write access via CLICKHOUSE_ALLOW_WRITE_ACCESS.
- Optional: destructive operations via CLICKHOUSE_ALLOW_DROP.
Risks and side effects
- If write access is enabled, AI might make unintended modifications.
- If DROP access is enabled, data deletion could occur accidentally.
- Credentials may be exposed via environment variables.
Troubleshooting
- Check if CLICKHOUSE_SECURE and CLICKHOUSE_PORT match.
- Ensure CLICKHOUSE_PORT is the HTTP port (8123/8443), not native TCP (9000/9440).
- Check server logs for detailed errors.
- Verify ClickHouse service is reachable and credentials are correct.
Use cases
Allow AI assistants to directly query ClickHouse for data insights.
Explore database schema, such as listing databases and tables.
Perform local data analysis with chDB without setting up a separate database.
Supported clients
Claude DesktopFull support