Clickhouse MCP Server

🚀 ClickHouse MCP Server

A Model Context Protocol (MCP) server that connects to a ClickHouse database and allows large language models (such as Claude) to explore and analyze data through natural language queries.

🚀 Quick Start

The ClickHouse MCP Server connects to a ClickHouse database and enables large language models like Claude to interact with the data using natural language.

✨ Features

• Connect to a ClickHouse database.
• Expose table schemas as resources.
• Run SQL queries from natural language instructions.
• Execute read - only SQL queries.
• Work with Claude Desktop on macOS.

🎥 Demo

Click to view the demo

📦 Installation

1. Clone this repository.
2. Install the dependencies:

npm install

3. Configure the environment variables in the .env file (refer to .env.example). Ensure to use a read - only database user to restrict DDL and DML execution.
4. Build the project:

npm run build

💻 Usage Examples

Basic Usage

Run the server locally

npm start

Integrate 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.

Advanced Usage

Available Resources

• db://info - Database information, including tables and schemas.
• table://{tableName}/schema - Schema of a specific table.
• table://{tableName}/sample - Sample data (5 rows) of a specific table.

Available Tools

• execute-sql - Execute read - only SQL queries on the database.
• natural-language-query - Ask questions about the data in natural language.

⚠️ Important Note

• This server only allows the execution of read - only SQL queries.
• Sensitive credentials should be securely stored in environment variables.
• The server performs basic validation to prevent the execution of DDL or DML statements.
• Always review query requests before execution.

📄 License

This project is licensed under the MIT license.