ClickHouse MCP Server
About
A Model Context Protocol (MCP) server that connects to ClickHouse databases and allows LLMs like Claude to explore and analyze data through natural language queries.
Details
- License
- MIT
Explore
- Connect to ClickHouse databases
- Expose table schemas as resources
- Run SQL queries from natural language instructions
- Execute read-only SQL queries
- Works with Claude Desktop for macOS
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
ClickHouse MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
1. Clone this repository
2. Install dependencies:
npm install
3. Configure your environment variables in a .env file (see .env.example for reference). Ensure you are using a read-only database user to restrict DDL and DML execution
4. Build the project:
npm run build
npm start
execute-sql
Run a read-only SQL query against the database
natural-language-query
Ask questions about your data in natural language
- execute-sql - Run a read-only SQL query against the database
- natural-language-query - Ask questions about your data in natural language
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"clickhouse mcp server": {
"clickhouse-analytics": {
"command": "node",
"args": [
"/absolute/path/to/clickhouse-mcp-server/dist/index.js"
],
"env": {
"CLICKHOUSE_URL": "",
"CLICKHOUSE_USERNAME": "",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_DATABASE": ""
}
}
}
}
}McpServers
{
"clickhouse-analytics": {
"command": "node",
"args": [
"/absolute/path/to/clickhouse-mcp-server/dist/index.js"
],
"env": {
"CLICKHOUSE_URL": "",
"CLICKHOUSE_USERNAME": "",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_DATABASE": ""
}
}
}A Model Context Protocol (MCP) server that connects to ClickHouse databases and allows LLMs like Claude to explore and analyze data through natural language queries.
Features
- Connect to ClickHouse databases
- Expose table schemas as resources
- Run SQL queries from natural language instructions
- Execute read-only SQL queries
- Works with Claude Desktop for macOS
Demo
https://github.com/user-attachments/assets/b496b9b0-5955-49d5-8c26-733f34662d8fInstallation
1. Clone this repository
2. Install dependencies:
npm install
3. Configure your environment variables in a .env file (see .env.example for reference). Ensure you are using a read-only database user to restrict DDL and DML execution
4. Build the project:
npm run build
Usage
Running the server locally
npm start
Integrating with Claude Desktop
1. Create or update your Claude Desktop configuration file:
- On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add the server configuration:
{
"mcpServers": {
"clickhouse-analytics": {
"command": "node",
"args": [
"/absolute/path/to/clickhouse-mcp-server/dist/index.js"
],
"env": {
"CLICKHOUSE_URL": "your_clickhouse_url",
"CLICKHOUSE_USERNAME": "your_username",
"CLICKHOUSE_PASSWORD": "your_password",
"CLICKHOUSE_DATABASE": "your_database"
}
}
}
}
3. Restart Claude Desktop
Available Features
Resources
- db://info - Database information including tables and schemas
- table://{tableName}/schema - Schema for a specific table
- table://{tableName}/sample - Sample data (5 rows) from a specific table
Tools
- execute-sql - Run a read-only SQL query against the database
- natural-language-query - Ask questions about your data in natural language
Security Considerations
- This server only allows read-only SQL queries
- Sensitive credentials should be stored securely in environment variables
- The server performs basic validation to prevent DDL or DML statement execution
- Always review query requests before execution
License
MIT
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
