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

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