clickhouse-mcp-server
3.2
If you are the rightful owner of clickhouse-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
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.
ClickHouse MCP Server
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-733f34662d8f
Installation
- Clone this repository
- Install dependencies:
npm install
- Configure your environment variables in a
.envfile (see.env.examplefor reference). Ensure you are using a read-only database user to restrict DDL and DML execution - Build the project:
npm run build
Usage
Running the server locally
npm start
Integrating with Claude Desktop
-
Create or update your Claude Desktop configuration file:
- On macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- On macOS:
-
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"
}
}
}
}
- Restart Claude Desktop
Available Features
Resources
db://info- Database information including tables and schemastable://{tableName}/schema- Schema for a specific tabletable://{tableName}/sample- Sample data (5 rows) from a specific table
Tools
execute-sql- Run a read-only SQL query against the databasenatural-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
